OpenClaude：支持任意模型后端的开源 coding-agent CLI

OpenClaude 是一个开源的编码智能体 CLI，支持云端和本地模型提供商。

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

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

Quick Start | Setup Guides | Providers | Development | VS Code Extension | Partners | Community

一个 CLI 横跨云端 API 和本地模型后端——无需为每个提供商单独配置工具

通过 /provider 提供引导式提供商设置和已保存的配置 profiles

统一的编码智能体工作流：bash、文件工具、grep、glob、agents、tasks、MCP 和 Web 工具

内置 VS Code 扩展，支持启动集成和主题支持

一位像素风英雄伙伴，每次你按 Enter 时就会射出一支箭（真的——见 Meet your buddy）

OpenClaude 需要 Node.js >= 22.0.0 来进行 npm 安装和运行。Bun 仅在源码构建和本地开发时需要。

npm install -g @gitlawb/openclaude@latest

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

paru -S openclaude

如果安装后提示 ripgrep 未找到，请系统级安装 ripgrep，并在启动 OpenClaude 前在同一终端确认 rg --version 能正常工作。

验证 / 排查已安装版本：

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

openclaude

运行 /provider 进行引导式提供商设置和已保存的用户级 provider profiles

运行 /onboard-github 进行 GitHub Models 接入引导

注意：OpenClaude 不会自动加载项目的 .env 文件。建议使用 /provider 命令进行设置，它会将 provider profiles 和凭证保存到 .openclaude-profile.json。如果你偏好环境变量，请显式导出它们，或运行 openclaude --provider-env-file .env 来加载 provider/setup 变量。从 shell 或启动器导出运行时/debug 旋钮。

恢复或分叉对话

通过会话 ID 恢复现有对话，或在当前目录下继续最近的对话：

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

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

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

分叉仅作用于对话分支。它不会创建文件系统隔离、复制你的工作树或创建 git worktree 分支。

在后台运行长时间的非交互式 prompt，与当前终端分离：

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 不会启动守护进程或网络服务，permission/provider/model/settings 标志的传递方式与前台 --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。

如果你之前使用 OpenClaude 时使用了 .claude 路径，请谨慎迁移：只将你为 OpenClaude 亲自创建的配置、命令、agents、skills、计划任务或其他文件复制到对应的 .openclaude 位置。不要全量复制 .claude，也不要复制 Claude Code 凭证或认证文件。对于 provider 认证，推荐重新运行 OpenClaude 的 provider 设置或导出 provider 特定的环境变量。

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

openclaude

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

openclaude

最快的本地 Ollama 配置

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

openclaude

$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 原生 Chat API，并在每次 Chat 请求时请求 32768 token 的上下文窗口，这样同会话历史不会被 Ollama 的 OpenAI 兼容中间层静默截断。如果需要不同的请求级上下文大小，请设置 OPENCLAUDE_OLLAMA_NUM_CTX 或 OLLAMA_CONTEXT_LENGTH。有关使用 ollama ps 进行验证，请参见高级设置。

面向初学者的指南：

macOS / Linux 快速入门

高级和源码构建指南：

Agent 路由和步骤限制

Repo Map（代码库智能）

工具驱动的编码工作流：Bash、文件读写编辑、grep、glob、agents、tasks、MCP 和斜杠命令

流式响应：实时 token 输出和工具进度

工具调用：多步工具循环，包含模型调用、工具执行和后续响应

图片：支持 vision 的 provider 的 URL 和 base64 图片输入

Provider profiles：引导式设置加上已保存的用户级 provider profile 支持

本地和远程模型后端：云端 API、本地服务器和 Apple Silicon 本地推理

代码库智能（repo map）：仓库的结构地图，按 PageRank 重要性排序，当启用 REPO_MAP 标志或设置 REPO_MAP 环境变量时自动注入上下文。使用 /repomap 检查（默认 2048 token）。详情见 docs/repo-map.md。

一位身怀招牌技能的伙伴：一位真彩色像素风英雄，生活在你的提示旁边，在你工作时做出反应。见下文。

运行 /buddy 来孵化一个伙伴——一个真彩色像素艺术英雄，它会站在你的提示旁边，空闲时眨眼发呆，每次你提交消息时释放招牌技能：

/buddy                  孵化（首次运行）或抚摸你的伙伴
/buddy set robinhood    绿衣弓箭手——每次按 Enter 就射箭
/buddy set kaio         金发战士——蓄力一道满屏能量波
/buddy set strawhat     伸缩拳，弹回
/buddy set merlin       闪闪发光的星光流
/buddy set kage         旋转手里剑
/buddy set ember        真正的热渐变龙息
/buddy set corsair      炮弹带烟尾
/buddy name Robin       给伙伴改名
/buddy set random       换回随机英雄

伙伴功能尊重 prefersReducedMotion，在低色终端中优雅降级为线稿艺术，可通过 /buddy mute 静音。需要至少 100 列宽的终端才能完整显示精灵。

OpenClaude 支持多提供商，但各提供商的行为并不完全一致。

Anthropic 特有功能在其他提供商上可能不存在

工具质量很大程度上取决于所选模型

较小的本地模型可能在长链路多步骤工具调用流程中表现吃力

某些提供商会施加比 CLI 默认值更低的最大输出限制，OpenClaude 会在可能的情况下自适应

AI/ML API 使用 OpenAI 兼容路由，默认模型为 gpt-4o，仅从其公共目录中筛选支持聊天的模型

Gitlawb Opengateway 是全新安装时的启动默认项，需要从 https://gitlawb.com/opengateway/keys 获取 API key。它使用一个 OpenAI 兼容的 base URL；可通过 /model 在 mimo-* 和 google/gemini-3.1-flash-lite-preview 之间切换，不要将 base URL 固定为 /v1/xiaomi-mimo。

Z.AI GLM Coding Plan 使用 https://api.z.ai/api/coding/paas/v4，默认模型为 glm-5.2。在该直接路由上，GLM-5.3-Flash 可选为 glm-5.3-flash 并支持图片输入。其 OpenClaude effort 选项有 low、high 和 xhigh，其中 xhigh 会请求 Z.AI max；GLM-5.3 和现有的 GLM-5.2 查询控制仍受支持。不对碰巧使用相同模型名的网关声称具备这些能力。

Xiaomi MiMo 在直接 OpenAI 兼容路由上使用 api-key header 认证，当前在 OpenClaude 中不支持 /usage 报告

GitHub Copilot 默认将子代理执行序列化，以减少 Premium 请求消耗——参见 Agent 路由和步骤限制以进行调整

为获得最佳效果，请使用具备强工具/函数调用能力的模型。

将不同代理路由到不同模型（成本优化、按模型优势分配工作），用 maxSteps 限制子代理工具步骤数，并调优 GitHub Copilot 子代理行为。通过 settings、代理 frontmatter 和环境变量配置：

在 ~/.openclaude/settings.json 中通过 agentModels + agentRouting 实现按代理的 provider/model 覆盖

仅指定模型的路由会复用当前 provider 的凭证

内置代理（Explore 和 Plan [功能门控]、验证 [功能门控：需要 VERIFICATION_AGENT + tengu_hive_evidence]、code-reviewer [需要 diff inline]）可按类型名路由

参见 Agent 路由和步骤限制获取完整指南。

默认情况下，WebSearch 在非 Anthropic 模型上使用 DuckDuckGo。这让 GPT-4o、DeepSeek、Gemini、Ollama 和其他 OpenAI 兼容提供商开箱即用获得免费网页搜索路径。

注意：DuckDuckGo 回退方案通过抓取搜索结果实现，可能会被限速、被屏蔽或受 DuckDuckGo 服务条款约束。如果需要更可靠的支持选项，请配置 Firecrawl。

对于 Anthropic 原生后端和 Codex 响应，OpenClaude 保持原生 provider 网页搜索行为。

WebFetch 可以工作，但其基础 HTTP 加 HTML 转 markdown 路径在 JavaScript 渲染的网站或阻止纯 HTTP 请求的网站上仍可能失败。

如果需要 Firecrawl 驱动的搜索/获取行为，请设置 Firecrawl API key：

export FIRECRAWL_API_KEY=your-key-here

启用 Firecrawl 后：

WebSearch 可使用 Firecrawl 的搜索 API，而 DuckDuckGo 仍作为非 Claude 模型的默认免费路径

WebFetch 使用 Firecrawl 的 scrape 端点而非原始 HTTP，正确处理 JS 渲染页面

免费层额度为 firecrawl.dev 500 credits。该 key 是可选的。

OpenClaude 可作为无头 gRPC 服务运行，支持双向流——将其智能体能力集成到其他应用程序、CI/CD 流水线或自定义 UI 中。用 npm run dev:grpc 启动；仓库附带一个测试 CLI 客户端。参见 Headless gRPC Server 了解 src/proto/openclaude.proto 的配置和客户端生成。

源码构建需要 Node.js >=22.0.0 和 Bun 1.3.13 或更高版本。

bun install
bun run build
node dist/cli.mjs

bun run dev — 从源码构建并启动

bun test — 完整单元测试套件（Bun 内置运行器）

bun test path/to/file.test.ts — 针对所改区域的聚焦运行

bun run test:coverage — 覆盖率输出到 coverage/lcov.info，可视化报告在 coverage/index.html（bun run test:coverage:ui 仅重建 UI）

bun run smoke — 冒烟测试

bun run doctor:runtime、bun run verify:privacy；PR 意图扫描请使用本地 pre-push 验证合约中的 fresh-upstream、explicit-ref 工作流

聚焦测试套件：bun run test:provider、bun run test:provider-recommendation。

要对启动器模块编译缓存进行基准测试，请构建 CLI 并运行：

bun run build
bun run benchmark:startup

基准测试需要 Node >=22.8.0（compile-cache API 加入的版本）；构建的 OpenClaude 启动器继续支持声明的 Node >=22.0.0 运行时范围。

基准测试默认 30 次独立进程预热运行和 10 次独立空缓存运行。它报告中位数、IQR、MAD、首次缓存填充运行、首次预热、Node/OS/CPU 详情、bundle 大小和 commit。直接 bundle 计时仅作为辅助诊断；完整的启动器结果才是决策信号。用 bun run benchmark:startup -- --warm-runs 40 --cold-runs 10 请求更大的样本集。基准测试记录结果但不强制执行 CI 中的时间阈值。

OpenClaude 让 Node 的标准 compile-cache 控制权保持权威性。设置 NODE_DISABLE_COMPILE_CACHE=1 可禁用该优化，包括对需要非缓存编译的 V8 覆盖率运行。

在打开或更新 PR 之前，运行权威的本地 pre-push 验证合约。以下命令对窄范围迭代有用，但它们不能替代必需的预检：

当你的改动影响共享运行时或 provider 逻辑时运行 bun run test:coverage

针对所改文件和流程的聚焦 bun test ... 运行

src/ - 核心 CLI/运行时

scripts/ - 构建、验证和维护脚本

docs/ - 设置、贡献者和项目文档

vscode-extension/openclaude-vscode/ - VS Code 扩展

.github/ - 仓库自动化、模板和 CI 配置

bin/ - CLI 启动器入口点

仓库在 vscode-extension/openclaude-vscode 中包含一个 VS Code 扩展，提供 OpenClaude 启动集成、支持 provider 的控制中心、编辑器内聊天、主题支持，以及可选的 Microsoft Foundry / Azure OpenAI 配置（端点、API 版本、部署、API key 通过 Secret Storage 注入到启动的终端）。参见该文件夹的 README。

如果你认为发现了安全问题，请参阅 SECURITY.md。

使用 GitHub Discussions 进行问答、创意和社区交流

使用 GitHub Issues 报告确认的 bug 和可操作的功能工作

加入 Discord 与社区实时聊天

关注 X 上的 @gitlawb 获取更新和公告

欢迎贡献。对于较大的改动，请先打开 issue 以便在实现前明确范围。参见 Development 了解构建、测试和 PR 前验证命令。

OpenClaude 是一个独立的社区项目，不隶属于 Anthropic、不受其认可或赞助。

OpenClaude 源自 Claude Code 代码库，此后经过大幅修改以支持多提供商和开放使用。"Claude" 和 "Claude Code" 是 Anthropic PBC 的商标。参见 LICENSE 了解更多。

MIT 许可证适用于 OpenClaude 贡献者的修改；派生的 Claude Code 仍为 Anthropic 所有。