OpenClaude

OpenClaude is an open-source coding-agent CLI for cloud and local model providers.

Use OpenAI-compatible APIs, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported backends while keeping one terminal-first workflow: prompts, tools, agents, MCP, slash commands, and streaming output.

OpenClaude is also mirrored to GitLawb: gitlawb.com/node/repos/z6MkqDnb/openclaude

Quick Start | Setup Guides | Providers | Source Build | VS Code Extension | Sponsors | Community

Sponsors

GitLawb	Bankr.bot	Atomic Chat	Xiaomi MiMo	Atlas Cloud

Star History

Why OpenClaude

• Use one CLI across cloud APIs and local model backends
• Save provider profiles inside the app with /provider
• Run with OpenAI-compatible services, Gemini, GitHub Models, Codex OAuth, Codex, Ollama, Atomic Chat, and other supported providers
• Keep coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
• Use the bundled VS Code extension for launch integration and theme support

Quick Start

Install

OpenClaude requires Node.js >=22.0.0 for npm installs and runtime. Bun is only needed for source builds and local development.

npm install -g @gitlawb/openclaude@latest

If you're on Arch Linux, you can install OpenClaude from the community-maintained AUR package:

paru -S openclaude

If the install later reports ripgrep not found, install ripgrep system-wide and confirm rg --version works in the same terminal before starting OpenClaude.

Verify / troubleshoot installed version:

openclaude --version
npm view @gitlawb/openclaude dist-tags
npm install -g @gitlawb/openclaude@latest

Start

openclaude

Inside OpenClaude:

• run /provider for guided provider setup and saved profiles
• run /onboard-github for GitHub Models onboarding

Note: OpenClaude does not automatically load project .env files. We recommend using the /provider command for setup, which saves provider profiles and credentials in .openclaude-profile.json. If you prefer environment variables, export them explicitly or run openclaude --provider-env-file .env for provider/setup variables. Export runtime/debug knobs from your shell or launcher.

Resume or fork a conversation

Resume an existing conversation by session ID, or continue the most recent conversation in the current directory:

openclaude --resume <session-id>
openclaude --continue

Add --fork-session to branch the conversation history into a new session ID instead of reusing the original transcript:

openclaude --resume <session-id> --fork-session
openclaude --continue --fork-session

Forking is conversation branching only. It does not create filesystem isolation, copy your working tree, or create a git worktree branch.

Background sessions

Run long non-interactive prompts detached from the current terminal:

openclaude --bg "fix failing tests"
openclaude --bg --name auth-refactor "refactor auth middleware"
openclaude ps
openclaude logs auth-refactor
openclaude logs auth-refactor -f
openclaude kill auth-refactor

Background sessions are local child processes. OpenClaude does not start a daemon or network service, and permission/provider/model/settings flags are passed to the child process the same way they are for a foreground --print run. Session metadata and logs are stored under the resolved OpenClaude config directory, usually ~/.openclaude/bg-sessions/; OPENCLAUDE_CONFIG_DIR can point OpenClaude somewhere else, with CLAUDE_CONFIG_DIR still supported as the legacy fallback. Session names can be reused after older sessions reach a terminal state; use the session ID to inspect older logs with the same name.

openclaude attach <id-or-name> currently reports the matching session and points to openclaude logs <id> -f; full terminal reattach is not implemented for local background sessions yet.

Fastest OpenAI setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export OPENAI_MODEL=gpt-4o

openclaude

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_API_KEY="sk-your-key-here"
$env:OPENAI_MODEL="gpt-4o"

openclaude

Fastest local Ollama setup

macOS / Linux:

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_BASE_URL=http://localhost:11434/v1
export OPENAI_MODEL=qwen2.5-coder:7b

openclaude

Windows PowerShell:

$env:CLAUDE_CODE_USE_OPENAI="1"
$env:OPENAI_BASE_URL="http://localhost:11434/v1"
$env:OPENAI_MODEL="qwen2.5-coder:7b"

openclaude

For Ollama, OpenClaude uses Ollama's native chat API and requests a 32768-token context window on each chat request so same-session history is not silently truncated by Ollama's OpenAI-compatible shim. Set OPENCLAUDE_OLLAMA_NUM_CTX or OLLAMA_CONTEXT_LENGTH if you need a different request-level context size. See Advanced Setup for verification with ollama ps.

Setup Guides

Beginner-friendly guides:

• Non-Technical Setup
• Windows Quick Start
• macOS / Linux Quick Start

Advanced and source-build guides:

• Advanced Setup
• Android Install

Supported Providers

Provider	Setup Path	Notes
OpenAI-compatible	/provider or env vars	Works with OpenAI, OpenRouter, DeepSeek, Groq, Mistral, LM Studio, and other compatible /v1 servers
Z.AI GLM Coding Plan	/provider or OpenAI-compatible env vars	Uses OPENAI_API_KEY at https://api.z.ai/api/coding/paas/v4 and defaults to glm-5.2
Hicap	/provider or OpenAI-compatible env vars	Uses api-key auth, discovers models from unauthenticated /models, and supports Responses mode for gpt- models
Fireworks AI	/provider or env vars	First-class provider with 276 curated models (DeepSeek, Qwen, Llama, Gemma, and more); uses FIREWORKS_API_KEY
ClinePass	/provider or env vars	AI model gateway with usage limits (5hr, weekly, monthly); uses CLINE_API_KEY at https://api.cline.bot/api/v1
Gemini	/provider or env vars	Supports API key only
GitHub Models	/onboard-github	Interactive onboarding with saved credentials
Codex OAuth	/provider	Opens ChatGPT sign-in in your browser and stores Codex credentials securely
Codex	/provider	Uses existing Codex CLI auth, OpenClaude secure storage, or env credentials
Gitlawb Opengateway	Startup default, /provider, or env vars	Smart gateway at https://opengateway.gitlawb.com/v1; requires an API key from https://gitlawb.com/opengateway/keys and routes Xiaomi MiMo and GMI Cloud partner models by OPENAI_MODEL
OpenCode Zen	/provider or env vars	Pay-as-you-go AI gateway (48 models); uses OPENCODE_API_KEY via https://opencode.ai/zen/v1; shared key with OpenCode Go
OpenCode Go	/provider or env vars	$10/mo subscription for open models (13 models); uses OPENCODE_API_KEY via https://opencode.ai/zen/go/v1; shared key with OpenCode Zen
Xiaomi MiMo	/provider or env vars	OpenAI-compatible API at https://mimo.mi.com; uses MIMO_API_KEY and defaults to mimo-v2.5-pro
NEAR AI	/provider or env vars	Unified gateway (Claude, GPT, Gemini + TEE open models); uses NEARAI_API_KEY at https://cloud-api.near.ai/v1
Ollama	/provider or env vars	Local inference with no API key
Atomic Chat	/provider, env vars, or bun run dev:atomic-chat	Local Model Provider; auto-detects loaded models
Bedrock / Vertex / Foundry	env vars	Anthropic-family cloud routes; Vertex is for Claude on Vertex AI, not arbitrary Model Garden models

What Works

• Tool-driven coding workflows: Bash, file read/write/edit, grep, glob, agents, tasks, MCP, and slash commands
• Streaming responses: Real-time token output and tool progress
• Tool calling: Multi-step tool loops with model calls, tool execution, and follow-up responses
• Images: URL and base64 image inputs for providers that support vision
• Provider profiles: Guided setup plus saved user-level provider profile support
• Local and remote model backends: Cloud APIs, local servers, and Apple Silicon local inference

Provider Notes

OpenClaude supports multiple providers, but behavior is not identical across all of them.

• Anthropic-specific features may not exist on other providers
• Tool quality depends heavily on the selected model
• Smaller local models can struggle with long multi-step tool flows
• Some providers impose lower output caps than the CLI defaults, and OpenClaude adapts where possible
• Gitlawb Opengateway is the fresh-install startup default and requires an API key from https://gitlawb.com/opengateway/keys. It uses one OpenAI-compatible base URL; switch between mimo-* and google/gemini-3.1-flash-lite-preview with /model, and do not pin the base URL to /v1/xiaomi-mimo.
• Z.AI GLM Coding Plan uses https://api.z.ai/api/coding/paas/v4 with glm-5.2 by default. Use glm-5.2?reasoning=high for enhanced reasoning, glm-5.2?reasoning=xhigh to request Z.AI reasoning_effort=max, or glm-5.2?thinking=disabled for faster direct answers.
• Xiaomi MiMo uses api-key header auth on the direct OpenAI-compatible route and currently does not support /usage reporting in OpenClaude

GitHub Copilot sub-agent optimization

When CLAUDE_CODE_USE_GITHUB=1, OpenClaude serializes sub-agent execution to reduce GitHub Copilot Premium Request consumption. Default behavior is GITHUB_COPILOT_MAX_SUBAGENTS=1 (synchronous, one sub-agent at a time). Tuning vars (all optional):

Var	Effect
GITHUB_COPILOT_MAX_SUBAGENTS=0	Suppress sub-agents entirely (sub-agents throw an error).
GITHUB_COPILOT_MAX_SUBAGENTS=1	Force synchronous execution. Default.
GITHUB_COPILOT_MAX_SUBAGENTS=2..10	Parsed/clamped but not enforced differently from =1 (any positive cap = synchronous).
GITHUB_COPILOT_ALLOW_SUBAGENTS=1	Re-enable parallel/background sub-agents, overriding the cap.
GITHUB_COPILOT_FORCE_SYNC_SUBAGENTS=1	Force synchronous execution regardless of cap.
GITHUB_COPILOT_OPTIMIZATION_DISABLED=1	Disable all of the above; sub-agents run as before this feature.

The is_async field reported in the tengu_agent_tool_selected event and the agent metadata now reflects the final execution mode (i.e., false when synchronous is forced). See .env.example for the full descriptions.

For best results, use models with strong tool/function calling support.

Agent step limits

Custom agents can define maxSteps as a positive integer to cap how many tool-use steps a sub-agent may execute. When the limit is reached, OpenClaude stops additional tool calls and asks the sub-agent for a concise final summary covering completed work, findings, remaining tasks, and whether another run is needed. Omitting maxSteps, or setting it to an invalid value such as 0 or malformed input, preserves the default unlimited behavior.

```markdown

name: bounded-researcher description: