OpenClaude：可运行于云端与本地模型的开源编程 Agent CLI

OpenClaude 是一款面向云端和本地模型供应商的开源编程 Agent CLI。

它支持 OpenAI 兼容 API、Gemini、GitHub Models、Codex OAuth、Codex、Ollama、Atomic Chat 及其他受支持后端，同时保持一套终端优先的工作流：提示词、工具、Agent、MCP、斜杠命令和流式输出。

OpenClaude 也镜像托管在 GitLawb：gitlawb.com/node/repos/z6MkqDnb/openclaude

• 一套 CLI 覆盖云端 API 和本地模型后端——无需为每个供应商使用不同工具。
• 通过 /provider 完成引导式供应商设置并保存配置文件。
• 在一处完成编程 Agent 工作流：bash、文件工具、grep、glob、Agent、任务、MCP 和 Web 工具。
• 内置 VS Code 扩展，支持启动集成和主题支持。
• 一位像素艺术风格的主角伙伴；每次按下 Enter 时，他都会射出一支箭（真的——参见“认识你的伙伴”）。

OpenClaude 的 npm 安装和运行时需要 Node.js >=22.0.0。只有进行源码构建和本地开发时才需要 Bun。

npm install -g @gitlawb/openclaude@latest

如果你使用 Arch Linux，可以通过社区维护的 AUR 软件包 安装 OpenClaude：

如果之后安装报告 ripgrep not found，请在系统范围内安装 ripgrep，并在启动 OpenClaude 前确认同一终端中 rg --version 可以正常运行。

验证 / 排查已安装版本：

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

在 OpenClaude 内部：

• 运行 /provider，进行引导式供应商设置并保存配置文件。
• 运行 /onboard-github，完成 GitHub Models 引导配置。

**注意：**OpenClaude 不会自动加载项目 .env 文件。建议使用 /provider 命令进行设置，该命令会将供应商配置文件和凭据保存至 .openclaude-profile.json。如果更倾向于使用环境变量，请显式导出它们，或运行 openclaude --provider-env-file .env 来加载供应商/设置变量。请从 shell 或启动器中导出运行时/调试控制变量。

恢复或分叉对话

通过会话 ID 恢复已有对话，或继续当前目录中最近一次对话：

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

添加 --fork-session，即可将对话历史分叉到新的会话 ID，而不是复用原始记录：

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

分叉仅针对对话分支。它不会创建文件系统隔离、复制工作树，也不会创建 git worktree 分支。

以脱离当前终端的方式运行长时间、非交互式提示：

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

后台会话是本地子进程。OpenClaude 不会启动守护进程或网络服务；权限、供应商、模型和设置标志会以与前台 --print 运行相同的方式传递给子进程。会话元数据和日志保存在解析后的 OpenClaude 配置目录下，通常为 ~/.openclaude/bg-sessions/；可通过 OPENCLAUDE_CONFIG_DIR 将 OpenClaude 指向其他位置。CLAUDE_CONFIG_DIR 会被 OpenClaude 的后台会话存储忽略。当较早会话进入终止状态后，其会话名称可被重复使用；如需查看同名旧会话的日志，请使用会话 ID。一项自然完成的会话会在进程以零状态码退出时记录为 exited，在返回非零状态码或处理终止信号时记录为 failed。若进程消失且未观察到结果，保守状态仍为 stale；显式成功执行 openclaude kill 会记录为 killed，且对于同一进程，killed 的优先级高于自然产生的 exited 或 failed 结果。终止结果单独保存在 bg-sessions/terminal/ 下；删除该目录会使已完成会话回退为基于存活状态推导的状态。OpenClaude 不会在 Windows 上推断 POSIX 信号名称。无法观测的强制终止、主机崩溃和断电，在所有平台上都会保持为 stale。

openclaude attach <id-or-name> 目前会报告匹配的会话，并提示使用 openclaude logs <id> -f；本地后台会话尚未实现完整的终端重新附加功能。

OpenClaude 配置迁移

默认情况下，OpenClaude 将自身配置存储在 ~/.openclaude 和 ~/.openclaude.json 下。它不会读取 ~/.claude、项目 .claude/ 目录或 CLAUDE_CONFIG_DIR；新用户可从空白 OpenClaude 配置开始，无需安装 Claude Code。

如果你此前通过 .claude 路径使用 OpenClaude，请有意识地进行迁移：仅将你个人为 OpenClaude 创建的设置、命令、Agent、技能、定时任务或其他文件，复制到相应的 .openclaude 位置。不要完整复制 .claude，也不要复制 Claude Code 的凭据或认证文件。对于供应商认证，建议重新运行 OpenClaude 的供应商设置，或导出供应商专属环境变量。

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

最快速的本地 Ollama 设置

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

对于 Ollama，OpenClaude 使用 Ollama 原生聊天 API，并会在每个聊天请求中请求 32768 token 的上下文窗口，以避免同一会话的历史记录被 Ollama 的 OpenAI 兼容适配层静默截断。如果需要不同的请求级上下文大小，请设置 OPENCLAUDE_OLLAMA_NUM_CTX 或 OLLAMA_CONTEXT_LENGTH。有关如何通过 ollama ps 进行验证，请参阅高级设置。

适合初学者的指南：

高级与源码构建指南：

供应商	设置路径	说明
OpenAI 兼容	/provider 或环境变量	适用于 OpenAI、OpenRouter、DeepSeek、Groq、Mistral、LM Studio 及其他兼容 /v1 的服务器
Z.AI GLM Coding Plan	/provider 或 OpenAI 兼容环境变量	在 https://api.z.ai/api/coding/paas/v4 使用 OPENAI_API_KEY，默认模型为 glm-5.2，并提供支持视觉能力的 glm-5.3-flash 选项
AI/ML API	/provider 或 AIMLAPI_API_KEY（设置指南）	使用 https://api.aimlapi.com/v1，通过 AIMLAPI_API_KEY 自动检测 OpenAI 兼容路由，发送 OpenClaude 归属请求头，并从公开 /models 目录发现支持聊天的模型
Concentrate	/provider 或 CONCENTRATE_API_KEY	位于 https://api.concentrate.ai/v1 的统一 OpenAI 兼容网关；默认使用 deepseek-v4-flash，并自动发现聊天模型目录
LLMTR	/provider 或 OpenAI 兼容环境变量	位于 https://llmtr.com/v1 的多模型网关；/provider 和 --provider llmtr 默认使用 deepseek/deepseek-v4-flash，而原始环境变量配置必须设置 OPENAI_BASE_URL=https://llmtr.com/v1 及 OPENAI_MODEL；在选择路由后接受 LLMTR_API_KEY 或 OPENAI_API_KEY，并从公开目录发现支持工具调用的 Chat Completions 模型
Command Code	/provider 或 OpenAI 兼容环境变量	位于 https://api.commandcode.ai/provider/v1 的混合 OpenAI 兼容网关；/provider 和 --provider commandcode 默认使用 deepseek/deepseek-v4-flash，而原始环境变量配置必须设置 OPENAI_BASE_URL=https://api.commandcode.ai/provider/v1 及 OPENAI_MODEL；选择路由后需要 CMD_API_KEY、COMMANDCODE_API_KEY 或官方 COMMAND_CODE_API_KEY，并从公开目录发现 Chat Completions 模型。此 Chat Completions 集成不支持 Claude 模型
ApiSmart	/provider 或 APISMART_API_KEY	使用 https://gw.apismart.ai/v1，默认模型为 DEEPSEEK_V4_FLASH，支持可选的 APISMART_MODEL 及经认证的模型发现
API Route	/provider 或 API_ROUTE_API_KEY	使用 https://global.api-route.com/v1，默认模型为 claude-sonnet-4-6，支持可选的 API_ROUTE_MODEL 及经认证的模型发现
Hicap	/provider 或 OpenAI 兼容环境变量	使用 api-key 认证，从无需认证的 /models 发现模型，并为 gpt- 模型支持 Responses 模式
Fireworks AI	/provider 或环境变量	一级支持的供应商，提供 276 个精选模型（DeepSeek、Qwen、Llama、Gemma 等）；使用 FIREWORKS_API_KEY
LongCat	/provider 或环境变量	美团 LongCat 的 OpenAI 兼容 API，地址为 https://api.longcat.chat/openai/v1；使用 LONGCAT_API_KEY，默认模型为 LongCat-2.0
ClinePass	/provider 或环境变量	设有使用限制（5 小时、每周、每月）的 AI 模型网关；在 https://api.cline.bot/api/v1 使用 CLINE_API_KEY
Gemini	/provider 或环境变量	仅支持 API key
GitHub Models	/onboard-github	提供交互式引导配置，并保存凭据
Codex OAuth	/provider	在浏览器中打开 ChatGPT 登录页面，并安全存储 Codex 凭据
Codex	/provider	使用现有 Codex CLI 认证、OpenClaude 安全存储或环境变量凭据
Gitlawb Opengateway	启动默认值、/provider 或环境变量	位于 https://opengateway.gitlawb.com/v1 的智能网关；需要从 https://gitlawb.com/opengateway/keys 获取 API key，并根据 OPENAI_MODEL 路由 Xiaomi MiMo 和 GMI Cloud 合作伙伴模型
OpenCode Zen	/provider 或环境变量	按量付费的 AI 网关（48 个模型）；通过 https://opencode.ai/zen/v1 使用 OPENCODE_API_KEY；与 OpenCode Go 共用密钥
OpenCode Go	/provider 或环境变量	每月 10 美元订阅开放模型服务（13 个模型）；通过 https://opencode.ai/zen/go/v1 使用 OPENCODE_API_KEY；与 OpenCode Zen 共用密钥
Xiaomi MiMo	/provider 或环境变量	位于 https://mimo.mi.com 的 OpenAI 兼容 API；使用 MIMO_API_KEY，默认模型为 mimo-v2.5-pro
NEAR AI	/provider 或环境变量	统一网关（Claude、GPT、Gemini + TEE 开放模型）；在 https://cloud-api.near.ai/v1 使用 NEARAI_API_KEY
Cloudflare Workers AI	/provider 或环境变量	位于 https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/v1 的 OpenAI 兼容 API；使用 CLOUDFLARE_API_TOKEN。请将 <ACCOUNT_ID> 替换为你的 Cloudflare 账户 ID。
Ollama	/provider 或环境变量	无需 API key 的本地推理
Atomic Chat	/provider、环境变量或 bun run dev:atomic-chat	本地模型供应商；自动检测已加载模型
Bedrock / Vertex / Foundry	环境变量	Anthropic 系列云端路由；Vertex 用于 Vertex AI 上的 Claude，而非任意 Model Garden 模型

• 工具驱动的编程工作流：Bash、文件读取/写入/编辑、grep、glob、Agent、任务、MCP 和斜杠命令
• 流式响应：实时 token 输出和工具进度
• 工具调用：支持模型调用、工具执行和后续响应的多步骤工具循环
• 图片：为支持视觉能力的供应商提供 URL 和 base64 图片输入。可使用 Ctrl+V 从剪贴板粘贴（Windows 上为 Alt+V）。1080p/4K 截图仍可附加。如果处理失败且图片超过

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 | Development | VS Code Extension | Partners | Community

• One CLI across cloud APIs and local model backends — no per-provider tooling
• Guided provider setup and saved profiles with /provider
• Coding-agent workflows in one place: bash, file tools, grep, glob, agents, tasks, MCP, and web tools
• A bundled VS Code extension for launch integration and theme support
• A pixel-art hero companion who fires an arrow every time you press Enter (really — see Meet your buddy)

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:

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

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.

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. CLAUDE_CONFIG_DIR is ignored for OpenClaude background-session storage. Session names can be reused after older sessions reach a terminal state; use the session ID to inspect older logs with the same name. A naturally finished session is recorded as exited when its process returns zero and failed when it returns nonzero or handles a termination signal. stale remains the conservative result when the process disappears without an observed outcome; an explicit successful openclaude kill is recorded as killed, and killed takes precedence over a natural exited or failed outcome for the same process. Terminal outcomes are stored separately under bg-sessions/terminal/; deleting that directory makes finished sessions fall back to liveness-derived status. OpenClaude does not infer POSIX signal names on Windows. Unobservable force termination, host crashes, and power loss remain stale on every platform.

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.

OpenClaude config cutover

OpenClaude stores its own config under ~/.openclaude and ~/.openclaude.json by default. It does not read ~/.claude, project .claude/ directories, or CLAUDE_CONFIG_DIR; new users can start with an empty OpenClaude config and do not need Claude Code installed.

If you previously used OpenClaude with .claude paths, migrate intentionally: copy only the settings, commands, agents, skills, scheduled tasks, or other files you personally created for OpenClaude into the matching .openclaude location. Do not blanket-copy .claude, and do not copy Claude Code credentials or auth files. For provider authentication, prefer running OpenClaude's provider setup again or exporting provider-specific environment variables.

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.

Beginner-friendly guides:

Advanced and source-build guides:

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, defaults to glm-5.2, and offers the vision-capable glm-5.3-flash option
AI/ML API	/provider or AIMLAPI_API_KEY (setup guide)	Uses https://api.aimlapi.com/v1, auto-detects the OpenAI-compatible route from AIMLAPI_API_KEY, sends OpenClaude attribution headers, and discovers chat-capable models from the public /models catalog
Concentrate	/provider or CONCENTRATE_API_KEY	Unified OpenAI-compatible gateway at https://api.concentrate.ai/v1; defaults to deepseek-v4-flash and auto-discovers the chat model catalog
LLMTR	/provider or OpenAI-compatible env vars	Multi-model gateway at https://llmtr.com/v1; /provider and --provider llmtr default to deepseek/deepseek-v4-flash, while raw env setup must set OPENAI_BASE_URL=https://llmtr.com/v1 and OPENAI_MODEL; accepts LLMTR_API_KEY or OPENAI_API_KEY after the route is selected and discovers tool-capable Chat Completions models from the public catalog
Command Code	/provider or OpenAI-compatible env vars	Hybrid OpenAI-compatible gateway at https://api.commandcode.ai/provider/v1; /provider and --provider commandcode default to deepseek/deepseek-v4-flash, while raw env setup must set OPENAI_BASE_URL=https://api.commandcode.ai/provider/v1 and OPENAI_MODEL; requires CMD_API_KEY, COMMANDCODE_API_KEY, or the official COMMAND_CODE_API_KEY after the route is selected and discovers Chat Completions models from the public catalog. Claude models are unsupported by this Chat Completions integration
ApiSmart	/provider or APISMART_API_KEY	Uses https://gw.apismart.ai/v1, defaults to DEEPSEEK_V4_FLASH, and supports optional APISMART_MODEL plus authenticated model discovery
API Route	/provider or API_ROUTE_API_KEY	Uses https://global.api-route.com/v1, defaults to claude-sonnet-4-6, and supports optional API_ROUTE_MODEL plus authenticated model discovery
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
LongCat	/provider or env vars	Meituan LongCat OpenAI-compatible API at https://api.longcat.chat/openai/v1; uses LONGCAT_API_KEY and defaults to LongCat-2.0
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
Cloudflare Workers AI	/provider or env vars	OpenAI-compatible API at https://api.cloudflare.com/client/v4/accounts/<ACCOUNT_ID>/ai/v1; uses CLOUDFLARE_API_TOKEN. Replace <ACCOUNT_ID> with your Cloudflare account id.
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

• 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. Paste from the clipboard with Ctrl+V (Alt+V on Windows). 1080p/4K screenshots still attach. If processing fails and the image is over the 5MB payload limit or the 8000px API edge, the prompt shows that error instead of "No image found". For Anthropic requests containing more than 20 images (including retained conversation history and tool results), local images must fit within 2000×2000 pixels. On Amazon Bedrock and Google Cloud Vertex AI, document blocks also count toward that 20-block threshold. OpenClaude attempts to resize them before sending; if processing cannot produce a compliant image, it reports an actionable error rather than silently dropping attachments. Resize the affected images or start a new conversation with fewer images (or documents on those partners).
• 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
• Codebase intelligence (repo map) : Structural map of the repository ranked by PageRank importance, auto-injected into context when the REPO_MAP flag is enabled or the REPO_MAP environment variable is set. Inspect with /repomap (2048-token default). See docs/repo-map.md for details.
• A companion with signature moves : A truecolor pixel-art hero who lives beside your prompt and reacts when you work. See below.

Run /buddy to hatch a companion — a truecolor pixel-art hero who stands beside your prompt, idles, blinks, and fires their signature move every time you submit a message:

/buddy                  hatch (first run) or pet your companion
/buddy set robinhood    the green archer — arrow shot on every Enter
/buddy set kaio         gold-haired warrior — charges a full-width energy wave
/buddy set strawhat     stretchy punch that snaps back
/buddy set merlin       twinkling sparkle stream
/buddy set kage         spinning shuriken
/buddy set ember        dragon fire with a real heat gradient
/buddy set corsair      cannonball with smoke trail
/buddy name Robin       rename your companion
/buddy set random       back to your rolled hero

Companions respect prefersReducedMotion, degrade gracefully to line art in low-color terminals, and can be silenced with /buddy mute. Requires a terminal at least 100 columns wide for the full sprite.

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
• AI/ML API uses the OpenAI-compatible route, defaults to gpt-4o, and only surfaces chat-capable models from its public catalog
• 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. On that direct route, GLM-5.3-Flash is selectable as glm-5.3-flash and accepts image input. Its OpenClaude effort choices are low, high, and xhigh, with xhigh requesting Z.AI max; GLM-5.3 and the existing GLM-5.2 query controls remain supported. These capabilities are not claimed for gateways that happen to carry the same model name.
• Xiaomi MiMo uses api-key header auth on the direct OpenAI-compatible route and currently does not support /usage reporting in OpenClaude
• GitHub Copilot serializes sub-agent execution by default to reduce Premium Request consumption — see Agent Routing and Step Limits for tuning

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

Route different agents to different models (cost optimization, splitting work by model strength), cap sub-agent tool steps with maxSteps, and tune GitHub Copilot sub-agent behavior. Configured via settings, agent frontmatter, and environment variables:

• per-agent provider/model overrides via agentModels + agentRouting in ~/.openclaude/settings.json
• model-only routes that reuse your current provider's credentials
• built-in agents (Explore and Plan [feature-gated], verification [feature-gated: requires VERIFICATION_AGENT + tengu_hive_evidence], code-reviewer [requires diff inline]) routable by type name

See Agent Routing and Step Limits for the full guide.

By default, WebSearch works on non-Anthropic models using configured search adapters and then DuckDuckGo. When the active provider is Ollama, OpenClaude first uses the signed-in local Ollama Web Search endpoint. Set OLLAMA_API_KEY to enable the hosted Ollama endpoint as a fallback.

Note: DuckDuckGo fallback works by scraping search results and may be rate-limited, blocked, or subject to DuckDuckGo's Terms of Service. If you want a more reliable supported option, configure Ollama Web Search or Firecrawl.

For Anthropic-native backends and Codex responses, OpenClaude keeps the native provider web search behavior.

To select Ollama search explicitly, use WEB_SEARCH_PROVIDER=ollama. A local Ollama route uses its configured OPENAI_BASE_URL or OLLAMA_BASE_URL; hosted search sends OLLAMA_API_KEY only to https://ollama.com/api/web_search.

WebFetch works, but its basic HTTP plus HTML-to-markdown path can still fail on JavaScript-rendered sites or sites that block plain HTTP requests.

Set a Firecrawl API key if you want Firecrawl-powered search/fetch behavior:

export FIRECRAWL_API_KEY=your-key-here

With Firecrawl enabled:

• WebSearch can use Firecrawl's search API while DuckDuckGo remains the default free path for non-Claude models
• WebFetch uses Firecrawl's scrape endpoint instead of raw HTTP, handling JS-rendered pages correctly

Free tier at firecrawl.dev includes 500 credits. The key is optional.

OpenClaude can run as a headless gRPC service with bidirectional streaming — integrate its agentic capabilities into other applications, CI/CD pipelines, or custom UIs. Start it with npm run dev:grpc; a test CLI client ships with the repo. See Headless gRPC Server for configuration and client generation from src/proto/openclaude.proto.

Use Node.js >=22.0.0 and Bun 1.3.13 or newer for source builds.

bun install
bun run build
node dist/cli.mjs

Day-to-day commands:

• bun run dev — build and launch from source
• bun test — full unit suite (Bun's built-in runner)
• bun test path/to/file.test.ts — focused runs for the areas you touch
• bun run test:coverage — coverage to coverage/lcov.info plus a visual report at coverage/index.html (bun run test:coverage:ui rebuilds just the UI)
• bun run smoke — smoke checks
• bun run doctor:runtime, bun run verify:privacy; for PR intent scanning, use the fresh-upstream, explicit-ref workflow in the local pre-push validation contract

Focused suites: bun run test:provider, bun run test:provider-recommendation.

To benchmark the launcher module compile cache, build the CLI and run:

bun run build
bun run benchmark:startup

The benchmark requires Node >=22.8.0, where the compile-cache API was added; the built OpenClaude launcher continues to support the declared Node >=22.0.0 runtime range.

The benchmark defaults to 30 separate-process warm runs and 10 isolated empty-cache runs. It reports the median, IQR, MAD, first cache-populating run, first warm-up, Node/OS/CPU details, bundle size, and commit. Direct bundle timings are included only as a secondary diagnostic; the full launcher result is the decision signal. Use bun run benchmark:startup -- --warm-runs 40 --cold-runs 10 to request a larger sample set. The benchmark records results without enforcing a timing threshold in CI.

OpenClaude leaves Node's standard compile-cache controls authoritative. Set NODE_DISABLE_COMPILE_CACHE=1 to disable the optimization, including for V8 coverage runs that require uncached compilation.

Before opening or updating a PR, run the authoritative local pre-push validation contract. The commands below are useful for narrow iteration, but they do not replace that required preflight:

• bun run build

• bun run smoke

• bun run test:coverage when your change affects shared runtime or provider logic

• focused bun test ... runs for the files and flows you changed

• src/ - core CLI/runtime

• scripts/ - build, verification, and maintenance scripts

• docs/ - setup, contributor, and project documentation

• vscode-extension/openclaude-vscode/ - VS Code extension

• .github/ - repo automation, templates, and CI configuration

• bin/ - CLI launcher entrypoints

The repo includes a VS Code extension in vscode-extension/openclaude-vscode for OpenClaude launch integration, provider-aware Control Center, in-editor chat, theme support, and optional Microsoft Foundry / Azure OpenAI configuration (endpoint, API version, deployment, API key via Secret Storage) injected into launched terminals. See that folder's README.

If you believe you found a security issue, see SECURITY.md.

Community

Contributions are welcome. For larger changes, open an issue first so the scope is clear before implementation. See Development for the build, test, and pre-PR validation commands.

OpenClaude is an independent community project and is not affiliated with, endorsed by, or sponsored by Anthropic.

OpenClaude originated from the Claude Code codebase and has since been substantially modified to support multiple providers and open use. "Claude" and "Claude Code" are trademarks of Anthropic PBC. See LICENSE for details.

MIT for OpenClaude contributors' modifications; the derived Claude Code remains Anthropic's. See more.