OpenClaude：runs anywhere. uses anyt…

一、它是什么：一个跑在任意模型上的编码 Agent CLI

（一）一句话定位

仓库的自我定位只有八个词：runs anywhere. uses anything。展开来说，OpenClaude 是一个开源的编码 Agent CLI，使用 OpenAI 兼容 API、Gemini、GitHub Models、Codex OAuth、Codex、Ollama、Atomic Chat 等受支持的后端，同时保留一套以终端为先的工作流：提示词、工具、Agent、MCP、斜杠命令与流式输出全都在这一个界面里完成。

（二）为什么需要它

README 的「Why OpenClaude」列出了几个它想解决的痛点：第一，用一套 CLI 打通云端 API 与本地模型后端，不再为每个供应商各配一套工具；第二，用 /provider 做引导式后端配置并保存档案；第三，把编码 Agent 工作流（bash、文件、grep、glob、agents、tasks、MCP、web 工具）都收进同一处；第四，附带一个 VS Code 扩展做启动集成与主题支持；第五，也是最有梗的一点——一只像素英雄伙伴，每次你敲回车就放一记必杀技。

二、安装与启动

（一）安装、启动与 onboard

OpenClaude 需要 Node.js >=22.0.0 才能装与跑（Bun 仅源码构建时需要）。一行命令即可全局安装：

npm install -g @gitlawb/openclaude@latest

Arch Linux 用户也可从社区维护的 AUR 包安装：paru -S openclaude。装好后直接 openclaude 启动；在交互界面里跑 /provider 做引导式后端配置并保存档案，跑 /onboard-github 接入 GitHub Models。注意它不会自动加载项目 .env，官方建议用 /provider 来配置，凭证会存进 .openclaude-profile.json；若坚持用环境变量，可显式导出或加 –provider-env-file .env。

（二）后台会话与续跑

支持用会话 ID 续接对话，或继续当前目录最近一次会话：openclaude –resume <session-id> 与 openclaude –continue。加 –fork-session 可把历史分叉成一个新会话。对于长任务，可以 detach 到后台：

openclaude --bg "fix failing tests"

，再用 openclaude ps、logs、kill 管理。这些后台会话是本地子进程，不会起 daemon 或网络服务，会话元数据与日志落在 ~/.openclaude/bg-sessions/，可用 OPENCLAUDE_CONFIG_DIR 改路径。

（三）配置迁移：独立于 Claude Code

OpenClaude 默认把配置存在 ~/.openclaude 与 ~/.openclaude.json，不读取 ~/.claude、项目内 .claude/ 目录或 CLAUDE_CONFIG_DIR。新用户从空配置起步，无需先装 Claude Code。若你以前把 OpenClaude 配在 .claude 路径下，应当只把 settings、commands、agents、skills、scheduled tasks 等你自己创建的文件搬到对应 .openclaude 位置，不要整体复制 .claude，更不要复制 Claude Code 的凭证或鉴权文件。

三、模型后端矩阵：一套 CLI 接遍所有供应商

OpenClaude 最硬核的部分，是它那张长长的「Supported Providers」表。它并不绑定某一家模型，而是把后端抽象成一组可切换的 provider：OpenAI 兼容（覆盖 OpenAI、OpenRouter、DeepSeek、Groq、Mistral、LM Studio 等 /v1 服务器）、Z.AI GLM Coding Plan、AI/ML API、Concentrate、LLMTR、Command Code、ApiSmart、Hicap、Fireworks AI（276 个精选模型）、LongCat、ClinePass、Gemini、GitHub Models、Codex OAuth、Codex、Gitlawb Opengateway（首发默认）、OpenCode Zen/Go、Xiaomi MiMo、NEAR AI、Cloudflare Workers AI、Ollama、Atomic Chat，以及 Bedrock/Vertex/Foundry 等云路由。

（一）云 API 与本地推理

这张表的含义是：无论是要调用云端大模型，还是跑本地推理（无需 API Key），OpenClaude 都用同一套提示词、工具与 Agent 框架承接。它也明确提示，不同 provider 行为并不完全一致——Anthropic 专属特性在其它后端上可能不存在，工具质量高度依赖所选模型，较小的本地模型在长多步工具链上会吃力，部分 provider 的输出上限比 CLI 默认更低。

README 的 Provider Notes 还给了几个具体提醒：Gitlawb Opengateway 是全新安装后的启动默认，需要从其官网申请 API Key，用一条 OpenAI 兼容基址在 mimo-* 与 google/gemini-3.1-flash-lite-preview 之间用 /model 切换；Z.AI GLM Coding Plan 走 https://api.z.ai/api/coding/paas/v4，默认 glm-5.2，并可选用带视觉的 glm-5.3-flash；Xiaomi MiMo 在该直连路由上用 api-key 头鉴权，目前尚不支持 /usage 上报；GitHub Copilot 默认会把子 Agent 执行串行化，以减少 Premium Request 消耗；AI/ML API 走 OpenAI 兼容路由、默认 gpt-4o。总结一句：想跑得稳，优先选工具/函数调用能力强的模型。

（二）最快接入：OpenAI 与 Ollama

文章给的最快上手路径非常直接。接 OpenAI 兼容服务：

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-your-key-here
export 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

对 Ollama，OpenClaude 会走其原生 chat API，并在每次请求里申请 32768 token 的上下文窗口，避免同会话历史被 Ollama 的 OpenAI 兼容层悄悄截断；需要不同请求级上下文可用 OPENCLAUDE_OLLAMA_NUM_CTX 或 OLLAMA_CONTEXT_LENGTH 调整。

四、把不同 Agent 路由到不同模型

（一）按 Agent 分派 provider/model

「Agents」一节展示了 OpenClaude 的进阶用法：可以把不同 Agent 路由到不同模型——既为成本优化，也按模型强弱拆分任务。具体通过 ~/.openclaude/settings.json 里的 agentModels + agentRouting 做每个 Agent 的 provider/model 覆盖，也支持只换模型、复用当前 provider 凭证的「纯模型路由」。内置 Agent（Explore、Plan、verification、code-reviewer）可按类型名路由，其中 verification 与 code-reviewer 需要特定开关或 diff 输入才启用。子 Agent 的工具步数还能用 maxSteps 封顶，并对 GitHub Copilot 的子 Agent 行为做调优。对团队而言，这意味着可以在同一个项目里让轻量本地模型跑 Explore、把强推理任务交给云端大模型，而不必为每次任务手动切环境。

这意味着你可以在同一个项目里，让一个轻量本地模型跑 Explore，把需要强推理的任务交给云端大模型，而不必为每次任务手动切换环境。

五、超越命令行：伙伴、搜索与 gRPC

（一）你的像素伙伴 Buddy

Run /buddy 就能孵出一只真彩像素英雄，站在提示符旁待机、眨眼，并在你每次提交消息时放出必杀技。可以 /buddy set robinhood 换成绿衣弓箭手（每次回车射箭），/buddy set kaio 换成金发战士（充能全宽能量波），还有 strawhat、merlin、kage、ember、corsair 等造型；/buddy name 改名，/buddy mute 静音。它会尊重 prefersReducedMotion，在低彩终端优雅降级为线稿，完整精灵需至少 100 列宽的终端。

各造型的必杀技各不相同，README 列出了一串可玩的组合：

• robinhood：绿衣弓箭手，每次回车射出一箭；
• kaio：金发战士，蓄力放出全宽能量波；
• strawhat：橡皮拳拉伸后弹回；
• merlin：闪烁的星光流；
• kage：旋转的手里剑；
• ember：带真实热感的龙息；
• corsair：拖着烟迹的炮弹；
• random：回到当初摇出的那只英雄。

它本质是个彩蛋，但恰好体现了项目「开源也可以很好玩」的气质——而它底下复用的，正是同一套终端渲染与事件机制。

（二）网络搜索与抓取

默认情况下，非 Anthropic 模型用 DuckDuckGo 做 WebSearch，让 GPT-4o、DeepSeek、Gemini、Ollama 等开箱即有免费搜索路径。DuckDuckGo 靠抓取搜索结果，可能限流或被拦，因此想更稳可配 Firecrawl：export FIRECRAWL_API_KEY=your-key-here，免费档含 500 额度。WebFetch 默认走基础 HTTP + HTML 转 Markdown，碰到 JS 渲染站点会失效，启用 Firecrawl 后改用其 scrape 端点即可正确处理。Anthropic 原生后端与 Codex 则保留 provider 自带的搜索行为。

（三）无头 gRPC 服务

OpenClaude 还能作为无头 gRPC 服务运行，支持双向流式通信，从而把它的 Agent 能力嵌进别的程序、CI/CD 流水线或自定义 UI。用 npm run dev:grpc 启动，仓库自带一个测试 CLI 客户端，配置与客户端可从 src/proto/openclaude.proto 生成。

六、工程化与生态

（一）仓库结构与开发

仓库结构很清晰：src/ 是核心 CLI/运行时，scripts/ 是构建与维护脚本，docs/ 是各类文档，vscode-extension/openclaude-vscode/ 是 VS Code 扩展，.github/ 是自动化与 CI，bin/ 是启动入口。源码构建用 Node >=22.0.0 与 Bun 1.3.13+，bun install && bun run build && node dist/cli.mjs 即可；日常有 bun run dev、bun test、bun run smoke 等。提交前必须跑本地 pre-push 校验契约，bun run build 与 bun run smoke 不能替代它。

（二）VS Code 扩展

仓库内带的 VS Code 扩展提供 OpenClaude 启动集成、provider 感知的 Control Center、编辑器内聊天、主题支持，以及可选的 Microsoft Foundry / Azure OpenAI 配置（端点、API 版本、部署、Secret Storage 里的 API Key），注入到被启动的终端中。这让它在 IDE 里也能保持统一的工作流。

七、能力边界与注意事项

README 的「What Works」与「Provider Notes」把能力与限制讲得很诚实。能用好的包括：工具驱动的编码工作流（bash、文件读写改、grep、glob、agents、tasks、MCP、斜杠命令）、流式响应、多步工具循环、图像输入（支持视觉的 provider）、provider 档案、本地与远程后端、代码库智能（repo map），以及前面那只伴侣。但需要注意：Anthropic 专属特性在别家可能不存在；工具质量看模型；小本地模型在长多步链路会吃力；部分 provider 输出上限更低，OpenClaude 会尽量自适应。

仓库智能（repo map）值得一提：它按 PageRank 重要性给仓库生成结构图，并在启用 REPO_MAP 标志或环境变量时自动注入上下文，用 /repomap 可查看（默认 2048 token）。这是它理解大型代码库的一个轻量机制。

八、协议与独立性声明

OpenClaude 的 License 段落写明：OpenClaude 贡献者所做的修改以 MIT 发布，而衍生的 Claude Code 部分仍归 Anthropic 所有。它还是 GitLawb 的镜像项目。仓库另有明确的 Disclaimer：OpenClaude 是独立的社区项目，与 Anthropic 无隶属、背书或赞助关系；它源于 Claude Code 代码库，但已大幅修改为支持多 provider 与开放使用，「Claude」「Claude Code」是 Anthropic PBC 的商标。

九、总结

OpenClaude 的吸引力在于「不站队」：它把编码 Agent 的能力抽象成一套终端工作流，再把几乎所有主流模型后端都接到这条工作流上。对既想用云端强模型、又想随时切回本地推理，或者希望在一个 CLI 里统一管理工具、Agent、MCP 与搜索的开发者来说，它提供了一个少见的、provider 中立的落脚点。那只会放必杀技的像素伙伴，则是它把「开源项目也可以很好玩」这件事做得很到位的小证据。

在撰写本文的过程中，我主要参考了 GitHub 仓库 Gitlawb/openclaude 的 README、Setup Guides 与 Providers 文档。文中数据（Star 数、版本要求等）以仓库公开信息为准，可能随版本更新而变化。