@xinggaoya/opencode

OpenClaude

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

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

OpenClaude 也镜像到了 GitLawb： gitlawb.com/node/repos/z6MkqDnb/openclaude

快速入门 | 设置指南 | 提供商 | 源码构建 | VS Code 扩展 | 赞助商 | 社区

赞助商

         

GitLawb      Bankr.bot      Atomic Chat

Star 历史

为什么选择 OpenClaude

• 在云 API 和本地模型后端之间使用一个 CLI
• 使用 /provider 在应用内保存提供商配置文件
• 支持 OpenAI 兼容服务、Gemini、GitHub Models、Codex OAuth、Codex、Ollama、Atomic Chat 和其他支持的提供商
• 在一个地方保持编程 Agent 工作流：bash、文件工具、grep、glob、Agent、任务、MCP 和网络工具
• 使用捆绑的 VS Code 扩展获得启动集成和主题支持

快速入门

安装

npm install -g @xinggaoya/opencode

如果安装后报告 ripgrep not found，请系统级安装 ripgrep，并在启动 OpenClaude 之前确认 rg --version 在同一终端中可用。

启动

openclaude

在 OpenClaude 内部：

• 运行 /provider 进行引导式提供商设置和保存配置文件
• 运行 /onboard-github 进行 GitHub Models 入门

最快的 OpenAI 设置

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 的 launch 命令

如果你已安装 Ollama，可以完全跳过环境变量设置：

ollama launch openclaude --model qwen2.5-coder:7b

这会自动设置 ANTHROPIC_BASE_URL、模型路由和认证，使所有 API 流量通过你的本地 Ollama 实例。支持你已拉取的任何模型 — 本地或云端。

设置指南

面向初学者的指南：

• 非技术设置
• Windows 快速入门
• macOS / Linux 快速入门

高级和源码构建指南：

• 高级设置
• Android 安装

支持的提供商

提供商	设置路径	备注
OpenAI 兼容	/provider 或环境变量	适用于 OpenAI、OpenRouter、DeepSeek、Groq、Mistral、LM Studio 和其他兼容的 /v1 服务器
Gemini	/provider 或环境变量	在当前 main 分支上支持 API 密钥、访问令牌或本地 ADC 工作流程
GitHub Models	/onboard-github	带有保存凭据的交互式入门
Codex OAuth	/provider	在浏览器中打开 ChatGPT 登录并安全存储 Codex 凭据
Codex	/provider	使用现有 Codex CLI 认证、OpenClaude 安全存储或环境凭据
Ollama	/provider、环境变量或 ollama launch	本地推理，无需 API 密钥
Atomic Chat	/provider、环境变量或 bun run dev:atomic-chat	本地模型提供商；自动检测已加载模型
Bedrock / Vertex / Foundry	环境变量	支持环境的其他提供商集成

功能特性

• 工具驱动的编码工作流：Bash、文件读取/写入/编辑、grep、glob、Agent、任务、MCP 和斜杠命令
• 流式响应：实时 token 输出和工具进度
• 工具调用：多步工具循环，包含模型调用、工具执行和后续响应
• 图片：支持视觉的提供商的 URL 和 base64 图片输入
• 提供商配置文件：引导式设置加保存的 .openclaude-profile.json 支持
• 本地和远程模型后端：云 API、本地服务器和 Apple Silicon 本地推理

提供商注意事项

OpenClaude 支持多个提供商，但行为并非在所有提供商之间完全相同。

• Anthropic 特定功能可能在其他提供商上不存在
• 工具质量高度依赖于所选模型
• 较小的本地模型在长多步工具流程中可能遇到困难
• 有些提供商的输出上限低于 CLI 默认值，OpenClaude 在可能的情况下会自适应

为获得最佳效果，请使用具有强工具/函数调用支持的模型。

Agent 路由

OpenClaude 可以通过对设置进行路由，将不同的 Agent 分配给不同的模型。这对于成本优化或按模型强度分配工作很有用。

添加到 ~/.openclaude.json：

{
  "agentModels": {
    "deepseek-v4-flash": {
      "base_url": "https://api.deepseek.com/v1",
      "api_key": "sk-your-key"
    },
    "gpt-4o": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-key"
    }
  },
  "agentRouting": {
    "Explore": "deepseek-v4-flash",
    "Plan": "gpt-4o",
    "general-purpose": "gpt-4o",
    "frontend-dev": "deepseek-v4-flash",
    "default": "gpt-4o"
  }
}

当没有找到路由匹配时，全局提供商作为回退。

注意： settings.json 中的 api_key 值以明文形式存储。请将此文件保密，不要提交到版本控制。

网络搜索和获取

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

注意： DuckDuckGo 回退通过抓取搜索结果工作，可能受到速率限制、被阻止或受 DuckDuckGo 服务条款约束。如果你想要更可靠的支持选项，请配置 Firecrawl。

对于 Anthropic 原生后端和 Codex 响应，OpenClaude 保持原生提供商网络搜索行为。

WebFetch 可以工作，但其基本的 HTTP 加 HTML 到 markdown 路径在 JavaScript 渲染的站点或阻止普通 HTTP 请求的站点上仍可能失败。

如果你想要 Firecrawl 支持的搜索/获取行为，请设置 Firecrawl API 密钥：

export FIRECRAWL_API_KEY=your-key-here

启用 Firecrawl 后：

• WebSearch 可以使用 Firecrawl 的搜索 API，而 DuckDuckGo 仍作为非 Claude 模型的默认免费路径
• WebFetch 使用 Firecrawl 的抓取端点而不是原始 HTTP，正确处理 JS 渲染的页面

firecrawl.dev 的免费层包含 500 积分。密钥是可选的。

无头 gRPC 服务器

OpenClaude 可以作为无头 gRPC 服务运行，允许你将其 Agent 能力（工具、bash、文件编辑）集成到其他应用程序、CI/CD 管道或自定义用户界面。服务器使用双向流式传输发送实时文本块、工具调用和对敏感命令的请求权限。

1. 启动 gRPC 服务器

在 localhost:50051 上将核心引擎作为 gRPC 服务启动：

npm run dev:grpc

配置

变量	默认值	描述
GRPC_PORT	50051	gRPC 服务器监听的端口
GRPC_HOST	localhost	绑定地址。使用 0.0.0.0 在所有接口上暴露（不建议在没有认证的情况下使用）

2. 运行测试 CLI 客户端

我们提供了一个轻量级 CLI 客户端，仅通过 gRPC 进行通信。它的行为就像主交互式 CLI 一样，通过 gRPC action_required 事件渲染颜色、流式传输 token 并提示你工具权限（y/n）。

在单独的终端中运行：

npm run dev:grpc:cli

注意：gRPC 定义位于 src/proto/openclaude.proto。你可以使用此文件在 Python、Go、Rust 或任何其他语言中生成客户端。

源码构建和本地开发

bun install
bun run build
node dist/cli.mjs

有用的命令：

• bun run dev
• bun test
• bun run test:coverage
• bun run security:pr-scan -- --base origin/main
• bun run smoke
• bun run doctor:runtime
• bun run verify:privacy
• 针对性运行 bun test ... 用于你修改的区域

测试和覆盖率

OpenClaude 使用 Bun 内置的测试运行器进行单元测试。

运行完整单元套件：

bun test

生成单元测试覆盖率：

bun run test:coverage

打开可视化覆盖率报告：

open coverage/index.html

如果你已有 coverage/lcov.info 并且只想重建 UI：

bun run test:coverage:ui

当你只修改一个区域时，使用针对性测试运行：

• bun run test:provider
• bun run test:provider-recommendation
• bun test path/to/file.test.ts

打开 PR 之前建议贡献者进行的验证：

• bun run build
• bun run smoke
• 当你的更改影响共享运行时或提供商逻辑时，运行 bun run test:coverage 以获得更广泛的单元覆盖率
• 对你更改的文件和流程运行针对性的 bun test ...

覆盖率输出写入 coverage/lcov.info，OpenClaude 还在 coverage/index.html 生成类似 git-activity 风格的热力图。

仓库结构

• src/ - 核心 CLI/运行时
• scripts/ - 构建、验证和维护脚本
• docs/ - 设置、贡献者和项目文档
• python/ - 独立 Python 辅助工具及其测试
• vscode-extension/openclaude-vscode/ - VS Code 扩展
• .github/ - 仓库自动化、模板和 CI 配置
• bin/ - CLI 启动器入口点

VS Code 扩展

仓库在 vscode-extension/openclaude-vscode 中包含一个 VS Code 扩展，用于 OpenClaude 启动集成、提供商感知控制中心 UI 和主题支持。

安全

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

社区

• 使用 GitHub 讨论 进行问答、想法和社区对话
• 使用 GitHub Issues 报告已确认的 bug 和可操作的特性工作

贡献

欢迎贡献。

对于更大的更改，在实现之前先开一个 issue，以便明确范围。有用的验证命令包括：

• bun run build
• bun run test:coverage
• bun run smoke
• 对你更改的文件和流程运行针对性的 bun test ...

免责声明

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

OpenClaude 源自 Claude Code 代码库，此后已大幅修改以支持多个提供商和开放使用。"Claude" 和 "Claude Code" 是 Anthropic PBC 的商标。详细信息请参阅 LICENSE。

许可证

请参阅 LICENSE。