OpenCode 集成
使用 OpenCode 开源终端 AI 编程助手搭配 QCode API
OpenCode 集成¶
⚠️ 重要提醒:需要开通 API 直接请求权限
使用 OpenCode 需要开通 API 直接请求权限。由于直接调用 API 没有 Claude Code 的 session 机制,tokens 开销会比较大,因此该权限默认关闭。
如需开通,请联系在线客服或发送邮件至 hi@qcode.cc,我们会为您已购买的 API Key 开通该权限。
OpenCode 是一款 100% 开源的终端 AI 编程助手,类似于 Claude Code,但提供了更多的灵活性和自定义能力。它支持多模型切换、LSP 集成、TUI 界面,并且不绑定任何特定的 AI 服务商。

项目介绍¶
OpenCode¶
OpenCode 是由 SST 团队开发的开源 AI 编程代理,主要特点包括:
-
100% 开源 - MIT 许可证,完全透明
-
多模型支持 - 可同时使用 Claude、OpenAI 等多种模型
-
原生 LSP 支持 - 内置语言服务器协议,提供智能代码分析
-
TUI 优先 - 专为终端用户设计,由 Neovim 用户打造
-
客户端/服务器架构 - 支持远程驱动,可在本机运行服务端,用移动端远程控制
-
双内置代理 -
build(默认,完整权限)和plan(只读,用于分析和规划)
项目数据(截至 2026 年 1 月):
-
GitHub Stars: 46.1k+
-
贡献者: 490+
-
版本: v1.0.223+
oh-my-opencode¶
oh-my-opencode 是 OpenCode 的增强插件,被称为"OpenCode 的类固醇",提供了专业级的 AI 编程体验:

核心特性:
-
异步子代理 - 类似 Claude Code 的并行任务处理能力
-
精选 Agent 配置 - 预配置的专业代理角色(Oracle、Librarian、Explore 等)
-
LSP/AST 工具 - 智能重构、代码分析、符号搜索等高级功能
-
Claude Code 兼容层 - 支持 Claude Code 的 hooks、commands、skills 配置
-
Sisyphus 主代理 - 基于 Claude Opus 4.6 的强大编排代理,支持后台并行任务
-
ultrawork 模式 - 只需在提示词中加入
ultrawork,自动启用最强并行模式
内置代理角色:
| 代理名称 | 模型 | 用途 |
|---|---|---|
| Sisyphus | Claude Opus 4.6 | 主编排代理,规划和委派任务 |
| Oracle | GPT 5.2 | 架构设计、代码审查、策略分析 |
| Librarian | Claude Sonnet 4.6 | 多仓库分析、文档查阅、实现示例 |
| Explore | Grok Code | 快速代码库探索和模式匹配 |
| Frontend UI/UX | Claude Sonnet 4.6 | 前端开发,UI/UX 设计 |
安装配置¶
步骤 1:安装 OpenCode¶
OpenCode 迭代非常快,请参考官方最新安装教程:
官方安装文档:https://opencode.ai/docs
常用安装方式:
# 使用 curl 安装(推荐)
curl -fsSL https://opencode.ai/install | bash
# 使用包管理器
npm install -g opencode # 或 bun/pnpm/yarn
# macOS Homebrew
brew install opencode
步骤 2:安装 oh-my-opencode(推荐)¶
oh-my-opencode 提供了开箱即用的专业配置,强烈建议安装:
bunx oh-my-opencode install
官方文档:https://github.com/code-yeongyu/oh-my-opencode
提示:安装时会询问你拥有哪些 AI 订阅(Claude、ChatGPT、Gemini),根据实际情况选择即可。
步骤 3:配置 QCode API¶
这是关键步骤!创建或编辑配置文件 ~/.config/opencode/opencode.json:
关于模型选择:下面的配置使用 QCode 提供的 Claude 系列和 GPT Codex 系列模型。我们推荐使用这两个系列的模型组合进行开发,它们在各类编程测评中表现优异。本站不售卖 Gemini、Grok 等模型,如果您确有需要,可以参考下面的配置格式去配置其他服务商的模型(但我们不太建议,因为 Gemini、Grok 在编程能力测评方面不如 Claude 与 Codex 系列)。
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://asia.qcode.cc/claude/v1"
}
},
"openai": {
"options": {
"baseURL": "https://asia.qcode.cc/openai"
}
}
},
"model": "anthropic/claude-opus-4-6",
"small_model": "anthropic/claude-haiku-4-5-20251001",
"default_agent": "build",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "ask",
"bash": "ask",
"webfetch": "ask",
"websearch": "ask",
"external_directory": "deny",
"doom_loop": "ask"
},
"agent": {
"plan": {
"mode": "primary",
"description": "规划/拆解/技术方案(只读,避免误改代码)",
"model": "anthropic/claude-opus-4-6",
"temperature": 0.1,
"prompt": "你是资深技术负责人。目标:把需求拆成可执行的步骤(含验收标准/风险/回滚)。默认只读,不要修改文件、不跑命令;如果确实需要执行,请先说明原因并建议切换到 build/codex。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "deny",
"bash": "deny",
"webfetch": "deny",
"websearch": "deny",
"external_directory": "deny",
"doom_loop": "deny"
}
},
"build": {
"mode": "primary",
"description": "主力开发(端到端实现/调试/修测试)- Claude Opus 4.6",
"model": "anthropic/claude-opus-4-6",
"temperature": 0.2,
"prompt": "你是主力软件工程 agent。优先:最小可行改动、可读性、可测试性。做改动前先快速说明方案;改完务必给出:关键 diff 点、如何本地验证(命令)、潜在边界条件。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "allow",
"bash": "allow",
"webfetch": "ask",
"websearch": "ask",
"external_directory": "deny",
"doom_loop": "ask"
}
},
"codex": {
"mode": "primary",
"description": "重构/迁移/大改动(Codex)- GPT-5.2",
"model": "openai/gpt-5.4",
"temperature": 0.2,
"prompt": "你是 Codex 风格的工程 agent,擅长大规模重构、迁移、代码审阅与复杂工具链协作。优先保持工程可运行:分步提交、每步可验证;遇到不确定先加防护与测试。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "allow",
"bash": "allow",
"webfetch": "ask",
"websearch": "ask",
"external_directory": "deny",
"doom_loop": "ask"
}
},
"review": {
"mode": "subagent",
"description": "代码审阅/第二大脑(只读)- GPT-5.1-Codex-Max",
"model": "openai/gpt-5.1-codex-max",
"temperature": 0.1,
"prompt": "你是严格的 code reviewer。输出:1) 关键风险(bug/安全/并发/边界)2) 可维护性建议 3) 最小修改建议(可用伪 diff)4) 必要的测试点。默认只读,不要改文件/跑命令。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "deny",
"bash": "deny",
"webfetch": "deny",
"websearch": "deny",
"external_directory": "deny",
"doom_loop": "deny"
}
},
"explore": {
"mode": "subagent",
"description": "快速扫代码/定位文件/总结上下文(只读)- Claude Haiku 4.5",
"model": "anthropic/claude-haiku-4-5-20251001",
"temperature": 0.1,
"prompt": "你是快速探索子 agent:用最少步骤定位相关文件/函数/调用链,给出清晰的路径与摘要。默认只读,不要改文件/跑命令。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "deny",
"bash": "deny",
"webfetch": "deny",
"websearch": "deny",
"external_directory": "deny",
"doom_loop": "deny"
}
},
"general": {
"mode": "subagent",
"description": "通用研究/写说明/对比方案(中等成本)- Claude Sonnet 4.6",
"model": "anthropic/claude-sonnet-4-6",
"temperature": 0.2,
"prompt": "你是通用分析子 agent:偏重解释、权衡、写文档与方案对比;默认只读,尽量不改代码。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "deny",
"bash": "deny",
"webfetch": "ask",
"websearch": "ask",
"external_directory": "deny",
"doom_loop": "deny"
}
},
"think": {
"mode": "subagent",
"description": "辅助思考/推演边界条件(只读)- GPT-5.2",
"model": "openai/gpt-5.4",
"temperature": 0.2,
"prompt": "你是推理与边界条件推演子 agent:针对设计、异常路径、并发/一致性、性能瓶颈给出结构化分析与建议。默认只读。",
"permission": {
"read": "allow",
"list": "allow",
"glob": "allow",
"grep": "allow",
"codesearch": "allow",
"lsp": "allow",
"edit": "deny",
"bash": "deny",
"webfetch": "deny",
"websearch": "deny",
"external_directory": "deny",
"doom_loop": "deny"
}
}
}
}
API 端点选择¶
根据你的网络情况,可以修改配置中 provider 的 baseURL:
| 端点 | Anthropic (Claude) | OpenAI (Codex) | 适用场景 |
|---|---|---|---|
| 域名直连(推荐) | https://asia.qcode.cc/claude/v1 |
https://asia.qcode.cc/openai |
全球用户,自动优选节点 |
| 香港 IP 直连 | http://103.218.243.5/claude/v1 |
http://103.218.243.5/openai |
国内用户备选 |
| 深圳 IP 直连 | http://103.236.53.153/claude/v1 |
http://103.236.53.153/openai |
中国大陆用户推荐 |
大陆用户推荐:使用深圳 IP 直连获得最佳速度,将
baseURL改为http://103.236.53.153/claude/v1和http://103.236.53.153/openai。
可用模型¶
QCode 目前支持以下热门模型:
Claude 系列(路径:/claude/v1):
-
claude-sonnet-4-6- Sonnet 4.6,性价比之选 -
claude-opus-4-6- Opus 4.6,最强推理能力 -
claude-haiku-4-5-20251001- Haiku 4.5,极速响应
OpenAI/Codex 系列(路径:/openai):
-
gpt-5.4- GPT 5.4 最新版(推荐) -
gpt-5.1-codex-max- Codex Max,编程专用 -
gpt-5.1-codex- Codex 标准版
配置说明¶
上述配置包含了完整的多 Agent 工作流:
| Agent | 模型 | 模式 | 用途 |
|---|---|---|---|
| plan | Claude Opus 4.6 | primary | 规划/拆解/技术方案(只读) |
| build | Claude Opus 4.6 | primary | 主力开发,端到端实现 |
| codex | GPT-5.2 | primary | 重构/迁移/大改动 |
| review | GPT-5.1-Codex-Max | subagent | 代码审阅(只读) |
| explore | Claude Haiku 4.5 | subagent | 快速扫代码/定位文件(只读) |
| general | Claude Sonnet 4.6 | subagent | 通用研究/写说明(只读) |
| think | GPT-5.2 | subagent | 辅助思考/推演边界条件(只读) |
你可以根据个人喜好调整各 Agent 的 model、prompt 和 permission 配置。
步骤 4:配置 API Key¶
打开 OpenCode 后,使用 /connect 命令配置 API Key:
配置 Anthropic (Claude)¶
-
在 OpenCode 中输入
/connect -
选择 Anthropic
-
选择 Manually enter API Key
-
输入你在 QCode 购买的 API Key
-
按 Enter 保存
配置 OpenAI (Codex)¶
-
输入
/connect -
选择 OpenAI
-
选择 Manually enter API Key
-
输入你在 QCode 购买的 API Key
-
按 Enter 保存
保存并重启¶
配置完成后:
-
输入
/exit退出 OpenCode -
重新打开 OpenCode
你的 API Key 会保存在 ~/.local/share/opencode/auth.json 文件中,后续可以直接编辑此文件进行调整。
验证配置¶
重新打开 OpenCode 后,可以通过以下方式验证配置是否成功:
# 启动 OpenCode
opencode
# 在 OpenCode 中测试
> 你好,请介绍一下你自己
如果能正常对话,说明配置成功!
使用技巧¶
ultrawork 模式¶
如果安装了 oh-my-opencode,只需在提示词中加入 ultrawork 或 ulw,即可启用最强的并行多模型编排模式:
ultrawork 帮我重构这个项目的认证模块
后台任务¶
使用 @ 语法调用专门的代理处理特定任务:
@oracle 帮我审查这段代码的架构设计
@librarian 查找类似功能的开源实现
@explore 搜索项目中所有的 API 端点
Tab 切换代理¶
按 Tab 键可以在 build 和 plan 代理之间切换:
-
build - 完整权限,用于开发工作
-
plan - 只读模式,用于分析和规划
常见问题¶
API 连接失败¶
-
检查 API 端点配置是否正确
-
确认 API Key 已正确保存
-
尝试切换到其他 API 端点(如深圳直连)
-
检查网络是否需要代理
模型不可用¶
确保在 opencode.json 中正确配置了模型定义,并且模型 ID 与 QCode 支持的模型名称一致。
oh-my-opencode 配置问题¶
参考官方文档:https://github.com/code-yeongyu/oh-my-opencode#configuration
相关链接¶
下一步¶
-
查看 VS Code 集成 了解 IDE 内使用方式
-
探索 Codex 集成 使用 OpenAI Codex 模型
-
学习 CLI 技巧 提升终端效率