OpenCode 接入 CodingPlanX 自定义模型
> 使用 OpenCode 开源终端 AI 编程助手搭配 CodingPlanX API，打造极致的命令行开发体验。
🌟 项目介绍
OpenCode 是一款 100% 开源的终端 AI 编程助手。它在设计思路上类似于 Claude Code，但提供了极高的灵活性和自定义能力。它不绑定任何特定的 AI 服务商，支持多模型自由切换、原生 LSP（语言服务器协议）集成以及极客风的 TUI（终端用户界面）。
1. OpenCode 核心特性
OpenCode 是由 SST 团队开发的开源 AI 编程代理，专为极客和终端重度用户打造：
- 🔓 100% 开源：基于 MIT 许可证，代码完全透明。
- 🧠 多模型支持：可同时配置并无缝切换 Claude、OpenAI、Google Gemini 等多种模型。
- ⚡ 原生 LSP 支持：内置语言服务器协议，提供极速、精准的智能代码分析与跳转。
- 🖥️ TUI 优先：专为终端用户设计，由资深 Neovim 用户倾力打造，全键盘操作。
- 🌐 C/S 架构：支持远程驱动，可在本机运行服务端，使用移动端或另一台电脑远程控制。
- 🔄 双内置代理：默认包含
build（完整读写权限，主力开发）和plan（只读权限，用于分析和规划）。
2. oh-my-opencode (推荐增强包)
oh-my-opencode 是 OpenCode 的最强增强插件，被社区称为 "OpenCode 的类固醇"，它能为你提供开箱即用的专业级 AI 编程体验。
核心增强特性：
- 异步子代理：类似 Claude Code 的并行任务处理能力，大幅提升复杂任务效率。
- 精选 Agent 配置：预配置了多个专业代理角色（如架构师、图书管理员、探索者等）。
- 高级 AST 工具：支持智能重构、代码深度分析、符号搜索等高级功能。
- 超强并行模式：只需在提示词中加入
ultrawork，即可自动启用最强并行模式。
内置代理角色一览表：
| 代理名称 | 推荐模型 | 核心用途 |
|---|---|---|
| 👑 Sisyphus | Claude Opus 4.6 | 主编排代理，负责全局规划和委派后台并行任务 |
| 🔮 Oracle | GPT 5.2 | 架构设计、深层代码审查、技术策略分析 |
| 📚 Librarian | Claude Sonnet 4.6 | 多仓库分析、官方文档查阅、寻找开源实现示例 |
| 🗺️ Explore | Grok Code / Haiku | 极速扫码、代码库探索和模式匹配 |
| 🎨 Frontend | Gemini 3 Pro | 专精前端开发，擅长创建精美且符合直觉的 UI/UX |
🚀 安装与配置
步骤 1：安装 OpenCode主程序
OpenCode 迭代速度非常快，建议使用官方推荐脚本安装最新版（官方文档）：
# 使用 curl 快速安装（推荐）
curl -fsSL https://opencode.ai/install | bash
# 或者使用 Node.js 包管理器
npm install -g opencode # bun / pnpm / yarn 均可
# macOS 用户也可以使用 Homebrew
brew install opencode
步骤 2：安装 oh-my-opencode（强烈推荐）
oh-my-opencode 提供了开箱即用的专业配置模板，免去繁琐的手动调优：
bunx oh-my-opencode install
> 💡 提示：安装过程中会进入交互式向导，询问你拥有哪些 AI 订阅（如 Claude、ChatGPT 等），请根据实际情况进行勾选。
步骤 3：配置 CodingPlanX API 节点与模型
这是最关键的一步！请使用文本编辑器创建或修改配置文件：~/.config/opencode/opencode.json。
> 🎯 关于模型选择： > 下方的配置模板使用了 CodingPlanX 提供的 Claude 系列 和 GPT Codex 系列 模型组合。它们在各类权威编程测评中表现最为优异，是开发者的黄金搭档。
将以下 JSON 内容完整复制并覆盖到你的 opencode.json 中：
{
"$schema": "https://opencode.ai/config.json",
"provider": {
"anthropic": {
"options": {
"baseURL": "https://api.codingplanx.ai/v1"
}
},
"openai": {
"options": {
"baseURL": "https://api.codingplanx.ai"
}
}
},
"model": "anthropic/claude-opus-4-5-20251101",
"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-5-20251101",
"temperature": 0.1,
"prompt": "你是资深技术负责人。目标：把需求拆成可执行的步骤（含验收标准/风险/回滚）。默认只读，不要修改文件、不跑命令；如果确实需要执行，请先说明原因并建议切换到 build/codex。",
"permission": { "edit": "deny", "bash": "deny", "webfetch": "deny", "websearch": "deny", "doom_loop": "deny" }
},
"build": {
"mode": "primary",
"description": "主力开发（端到端实现/调试/修测试）- Claude Opus 4.6",
"model": "anthropic/claude-opus-4-5-20251101",
"temperature": 0.2,
"prompt": "你是主力软件工程 agent。优先：最小可行改动、可读性、可测试性。做改动前先快速说明方案；改完务必给出：关键 diff 点、如何本地验证（命令）、潜在边界条件。",
"permission": { "edit": "allow", "bash": "allow", "webfetch": "ask", "websearch": "ask", "doom_loop": "ask" }
},
"codex": {
"mode": "primary",
"description": "重构/迁移/大改动（Codex）- GPT-5.2",
"model": "openai/gpt-5.2-2025-12-11",
"temperature": 0.2,
"prompt": "你是 Codex 风格的工程 agent，擅长大规模重构、迁移、代码审阅与复杂工具链协作。优先保持工程可运行：分步提交、每步可验证；遇到不确定先加防护与测试。",
"permission": { "edit": "allow", "bash": "allow", "webfetch": "ask", "websearch": "ask", "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": { "edit": "deny", "bash": "deny", "webfetch": "deny", "websearch": "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": { "edit": "deny", "bash": "deny" }
},
"general": {
"mode": "subagent",
"description": "通用研究/写说明/对比方案（中等成本）- Claude Sonnet 4.6",
"model": "anthropic/claude-sonnet-4-5-20250929",
"temperature": 0.2,
"prompt": "你是通用分析子 agent：偏重解释、权衡、写文档与方案对比；默认只读，尽量不改代码。",
"permission": { "edit": "deny", "bash": "deny" }
},
"think": {
"mode": "subagent",
"description": "辅助思考/推演边界条件（只读）- GPT-5.2",
"model": "openai/gpt-5.2-2025-12-11",
"temperature": 0.2,
"prompt": "你是推理与边界条件推演子 agent：针对设计、异常路径、并发/一致性、性能瓶颈给出结构化分析与建议。默认只读。",
"permission": { "edit": "deny", "bash": "deny" }
}
}
}
步骤 4：配置 API Key
由于我们配置了两个提供商（Anthropic 和 OpenAI），需要在 OpenCode 内部绑定你在 CodingPlanX 获取的 API Key。
- 在终端输入
opencode启动程序。 - 在对话框输入
/connect命令。 - 配置 Claude：
- 选择 Anthropic -> 选择 Manually enter API Key。
- 粘贴你的 CodingPlanX API Key 并回车保存。
- 配置 OpenAI：
- 再次输入
/connect。 - 选择 OpenAI -> 选择 Manually enter API Key。
- 粘贴你的 CodingPlanX API Key 并回车保存。
- 再次输入
- 输入
/exit退出，然后重新启动opencode让配置生效。
> 🔐 注：你的 API Key 会被安全地保存在本地的 ~/.local/share/opencode/auth.json 文件中。
💡 高阶使用技巧
完成配置后，在终端输入 opencode 即可开始对话：
> 你好，请读取当前目录下的 package.json，并介绍一下这个项目。
1. ⚡ Ultrawork 终极并行模式
如果你安装了 oh-my-opencode，只需在提示词中加入 ultrawork 或简写 ulw，OpenCode 就会召唤主代理进行任务拆解，并派发给后台子代理并行处理：
> ultrawork 帮我重构 src/auth 目录下的认证模块，并补充单元测试。
2. 🎯 @ 语法定向召唤代理
你可以使用 @ 符号，将特定任务精准派发给我们在 JSON 中配置的专业代理：
> @review 帮我审查一下刚提交的 login.ts 逻辑有没有安全漏洞。
> @explore 搜索项目中所有调用了 getUserInfo 的 API 端点。
> @general 帮我对比一下当前项目用 React Context 还是 Redux 更好。
3. 🔄 Tab 键极速切换工作模式
在输入框按 Tab 键，可以在主代理之间快速轮询切换：
- build：主力模式，具备完整的文件读写和终端执行权限。
- plan：安全模式，只读权限，用于前期的需求拆解、架构分析和技术规划，防止 AI 意外修改代码。
🛠️ 常见问题排查 (FAQ)
Q1：提示 API 连接失败或超时？
- 检查
opencode.json中的baseURL是否正确。 - 检查终端是否开启了代理冲突（通常使用直连 IP 即可绕过系统代理问题）。
Q2：提示 "Model not found" 或模型不可用？
- 确认配置文件中的模型 ID（如
claude-opus-4-5-20251101）与 CodingPlanX 官方提供的模型列表完全一致，不要拼错。
Q3：oh-my-opencode 插件报错？
- 插件处于高速开发期，若遇到 Bug，请尝试更新：
bunx oh-my-opencode update。 - 更多配置问题请查阅 oh-my-opencode 官方文档。