OpenCode 2.1.4 接入

OpenCode 2.1.4 接入 QCode.cc：opencode.json 配置两个 provider 的 baseURL，/connect 填 API Key。

需要 API Key？ 前往注册 →·端点与 Base URL →

最后核实：2026-10-26 · 📄 依据官方文档（OpenCode 2 v2.1.4，2026-10-23 发布；OpenCode 1 最新 v1.19.4，2026-10-22 发布（仓库现为 anomalyco/opencode）；本页 2026-10-20 核对时为 v2.1.0 与 v1.19.3）

接入速览¶

⚠️ 重要提醒：需要开通 API 直接请求权限

使用 OpenCode 需要开通 API 直接请求权限。由于直接调用 API 没有 Claude Code 的 session 机制，tokens 开销会比较大，因此该权限默认关闭。

如需开通，请联系在线客服或发送邮件至 hi@qcode.cc，我们会为您已购买的 API Key 开通该权限。

OpenCode 是一款 100% 开源的终端 AI 编程助手，类似于 Claude Code，支持多模型切换、LSP 集成和 TUI，且不绑定特定 AI 服务商。把它接到 QCode：在 ~/.config/opencode/opencode.json 里为 Anthropic 和 OpenAI 的 provider 写入 baseURL，用 /connect 填入 QCode API Key，退出重开后问一句就能验证。使用前需开通 API 直接请求权限（默认关闭，可联系在线客服或发邮件到 hi@qcode.cc）。

快速开始：

1. 安装 OpenCode：curl -fsSL https://opencode.ai/install | bash（也可用 npm 或 Homebrew）。
2. 编辑 ~/.config/opencode/opencode.json：Anthropic 的 baseURL 填 https://api.qcode.cc/claude/v1，OpenAI 填 https://api.qcode.cc/openai/v1。
3. /connect 分别选择 Anthropic / OpenAI，手动输入 API Key，/exit 后重新打开。
4. 在 OpenCode 里问一句「你好，请介绍一下你自己」验证。

项目介绍¶

OpenCode¶

OpenCode 是由 SST 团队开发的开源 AI 编程代理，主要特点包括：

• 100% 开源 - MIT 许可证，完全透明

• 多模型支持 - 可同时使用 Claude、OpenAI 等多种模型

• 原生 LSP 支持 - 内置语言服务器协议，提供智能代码分析

• TUI 优先 - 专为终端用户设计，由 Neovim 用户打造

• 客户端/服务器架构 - 支持远程驱动，可在本机运行服务端，用移动端远程控制

• 双内置代理 - build（默认，完整权限）和 plan（只读，用于分析和规划）

OpenCode 2（2026-10-20）：OpenCode 2 接受并保留 lsp 配置，但不运行语言服务器、不提供 LSP 工具，也不产出 LSP 诊断（官方文档）。

项目数据（截至 2026-10-20）：

• GitHub Stars：218,397（截至 2026-10-20；2026-10-15 为 213k+）

• Repository: anomalyco/opencode (formerly sst/opencode; old URL redirects)

• Version：OpenCode 2 v2.1.4（2026-10-23）；OpenCode 1 最新 v1.19.4（2026-10-22）。此前所列的 v2.1.0（2026-10-20）、v1.19.3（2026-10-16）与 v1.19.0（2026-10-11）现为历史版本。

oh-my-opencode¶

oh-my-opencode 是第三方开发的 OpenCode 增强插件，社区常称它为"OpenCode 的类固醇"。需要注意：截至 2026-10-15，它的仓库已更名为 code-yeongyu/oh-my-openagent，README 把项目改称 OmO，主入口是独立的 omo 命令；原来的 OpenCode 版在 README 里称作「OpenCode edition」，并提供 omo setup 迁移（见其 Migrating from OpenCode 文档）。README 仍保留 ultrawork 关键字等用法。

因为它的形态已经变了，本文不再列出旧版的内置代理角色表，也不再给 bunx oh-my-opencode install 这类旧安装命令。需要时请以官方 README 为准：code-yeongyu/oh-my-openagent。下面的 OpenCode 配置不依赖它。

截至 2026-10-20，README 将项目标注为 OmO 5.0，给出的安装命令是 curl -fsSL https://get.omo.dev/install.sh | bash；README 还写明 OmO 运行在 senpi 上，senpi 是 OmO 自己对 pi 的分叉。

安装配置¶

步骤 1：安装 OpenCode¶

OpenCode 迭代非常快，请参考官方最新安装教程：

官方安装文档：https://opencode.ai/docs

常用安装方式：

# 使用 curl 安装（推荐）
curl -fsSL https://opencode.ai/install | bash

# 使用包管理器
npm install -g opencode-ai  # 或 bun/pnpm/yarn

# macOS Homebrew
brew install anomalyco/tap/opencode

截至 2026-10-20，这个脚本只安装 OpenCode 1。OpenCode 2 使用单独的安装命令，见下文 OpenCode 2。

步骤 2：oh-my-opencode（可选）¶

oh-my-opencode 不是必需的。如果想使用它，请按上文链接里的官方 README 安装；本文后面的 OpenCode 配置不依赖它。

步骤 3：配置 QCode API¶

这是关键步骤！创建或编辑配置文件 ~/.config/opencode/opencode.json：

关于模型选择：下面的配置使用 QCode 提供的 Claude 5.5 系和 GPT 系列。日常默认用 claude-sonnet-5-5 / claude-opus-5-5，轻量任务用 claude-haiku-5-5；GPT 用 gpt-6.1-sol / gpt-6-sol / gpt-5.6-terra，可调型号以 qcode.cc/models 为准。QCode 暂不提供 Gemini 模型，也不提供 Grok，所以配置里只有 anthropic 和 openai 两个 provider。国产模型 id 见 国产模型接入。

关于 baseURL：OpenCode 官方文档里 Anthropic 的 baseURL 示例写到 /v1（https://api.anthropic.com/v1），所以这里同样写到 /v1：Anthropic 用 https://api.qcode.cc/claude/v1，OpenAI 用 https://api.qcode.cc/openai/v1，与 接入点与 API 格式 中的路径一致。

关于国产模型：OpenCode 的内置 openai provider（@ai-sdk/openai）走 Responses 接口，而 QCode 的 Responses 接口不服务国产模型。国产模型请另建一个 @ai-sdk/openai-compatible provider（走 chat/completions，baseURL 为 https://api.qcode.cc/openai/v1），模型 id 见 国产模型接入。OpenCode 官方 providers 文档写明：走 /v1/responses 用 @ai-sdk/openai，走 /v1/chat/completions 用 @ai-sdk/openai-compatible。

{
  "$schema": "https://opencode.ai/config.json",

  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.qcode.cc/claude/v1"
      }
    },
    "openai": {
      "options": {
        "baseURL": "https://api.qcode.cc/openai/v1"
      }
    }
  },

  "model": "anthropic/claude-opus-5-5",
  "small_model": "anthropic/claude-haiku-5-5",
  "default_agent": "build",

  "permission": {
    "read": "allow",
    "list": "allow",
    "glob": "allow",
    "grep": "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-5-5",
      "prompt": "你是资深技术负责人。目标：把需求拆成可执行的步骤（含验收标准/风险/回滚）。默认只读，不要修改文件、不跑命令；如果确实需要执行，请先说明原因并建议切换到 build/codex。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "build": {
      "mode": "primary",
      "description": "主力开发（端到端实现/调试/修测试）- Claude Opus 5.5",
      "model": "anthropic/claude-opus-5-5",
      "prompt": "你是主力软件工程 agent。优先：最小可行改动、可读性、可测试性。做改动前先快速说明方案；改完务必给出：关键 diff 点、如何本地验证（命令）、潜在边界条件。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "codex": {
      "mode": "primary",
      "description": "重构/迁移/大改动（Codex）- GPT-6.1 Sol",
      "model": "openai/gpt-6.1-sol",
      "prompt": "你是 Codex 风格的工程 agent，擅长大规模重构、迁移、代码审阅与复杂工具链协作。优先保持工程可运行：分步提交、每步可验证；遇到不确定先加防护与测试。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "allow",
        "bash": "allow",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "ask"
      }
    },

    "review": {
      "mode": "subagent",
      "description": "代码审阅/第二大脑（只读）- GPT-5.6 Terra",
      "model": "openai/gpt-5.6-terra",
      "prompt": "你是严格的 code reviewer。输出：1) 关键风险（bug/安全/并发/边界）2) 可维护性建议 3) 最小修改建议（可用伪 diff）4) 必要的测试点。默认只读，不要改文件/跑命令。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "explore": {
      "mode": "subagent",
      "description": "快速扫代码/定位文件/总结上下文（只读）- Claude Haiku 5.5",
      "model": "anthropic/claude-haiku-5-5",
      "prompt": "你是快速探索子 agent：用最少步骤定位相关文件/函数/调用链，给出清晰的路径与摘要。默认只读，不要改文件/跑命令。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "general": {
      "mode": "subagent",
      "description": "通用研究/写说明/对比方案（中等成本）- Claude Sonnet 5.5",
      "model": "anthropic/claude-sonnet-5-5",
      "prompt": "你是通用分析子 agent：偏重解释、权衡、写文档与方案对比；默认只读，尽量不改代码。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "ask",
        "websearch": "ask",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    },

    "think": {
      "mode": "subagent",
      "description": "辅助思考/推演边界条件（只读）- GPT-6.1 Sol",
      "model": "openai/gpt-6.1-sol",
      "prompt": "你是推理与边界条件推演子 agent：针对设计、异常路径、并发/一致性、性能瓶颈给出结构化分析与建议。默认只读。",
      "permission": {
        "read": "allow",
        "list": "allow",
        "glob": "allow",
        "grep": "allow",
        "lsp": "allow",
        "edit": "deny",
        "bash": "deny",
        "webfetch": "deny",
        "websearch": "deny",
        "external_directory": "deny",
        "doom_loop": "deny"
      }
    }
  }
}

API 端点选择¶

根据你的网络情况，可以修改配置中 provider 的 baseURL：

大陆用户推荐：使用 asia.qcode.cc（亚洲接入点），把 baseURL 改为上表亚洲一行的两个地址。

可用模型¶

QCode 目前支持以下热门模型（完整清单与单价见 qcode.cc/models）：

Claude 系列（路径：/claude/v1）：

• claude-opus-5-5 - 当前主力旗舰（claude-opus-5、claude-opus-4-8 仍可调用）

• claude-sonnet-5-5 - 日常默认平衡档（claude-sonnet-5、claude-sonnet-4-6 仍可调用）

• claude-haiku-5-5 - Haiku 5.5，极速响应

OpenAI/Codex 系列（路径：/openai/v1）：

• gpt-6.1-sol - 主推旗舰，1.05M 上下文

• gpt-6-sol - GPT-6 Sol，1.05M 上下文

• gpt-5.6-terra - 编程/Codex CLI

• gpt-5.6-sol - 5.6 同级变体

QCode 暂不提供 Gemini 系列，也不提供 gpt-6-luna / gpt-5.6-luna。

配置说明¶

上述配置包含了完整的多 Agent 工作流：

你可以根据个人喜好调整各 Agent 的 model、prompt 和 permission 配置。

步骤 4：配置 API Key¶

打开 OpenCode 后，使用 /connect 命令配置 API Key：

配置 Anthropic (Claude)¶

1. 在 OpenCode 中输入 /connect

2. 选择 Anthropic

3. 选择 Manually enter API Key

4. 输入你在 QCode 购买的 API Key

5. 按 Enter 保存

配置 OpenAI (Codex)¶

1. 输入 /connect

2. 选择 OpenAI

3. 选择 Manually enter API Key

4. 输入你在 QCode 购买的 API Key

5. 按 Enter 保存

保存并重启¶

配置完成后：

1. 输入 /exit 退出 OpenCode

2. 重新打开 OpenCode

你的 API Key 会保存在 ~/.local/share/opencode/auth.json 文件中，后续可以直接编辑此文件进行调整。

OpenCode 2 的 API Key 与 OAuth 令牌保存在服务端的 SQLite 数据库中；V2 在数据库迁移时会导入旧的 auth.json 中受支持的凭据（2026-10-20 官方文档）。

验证配置¶

重新打开 OpenCode 后，可以通过以下方式验证配置是否成功：

# 启动 OpenCode
opencode

# 在 OpenCode 中测试
> 你好，请介绍一下你自己

如果能正常对话，说明配置成功！

使用技巧¶

ultrawork 模式¶

旧版 oh-my-opencode（OpenCode edition）支持在提示词中加入 ultrawork 或 ulw 来启用并行多模型编排；新版 OmO 是独立的 omo 命令，用法以其 README 为准。旧版示例：

ultrawork 帮我重构这个项目的认证模块

Tab 切换代理¶

按 Tab 键可以在 build 和 plan 代理之间切换：

• build - 完整权限，用于开发工作

• plan - 只读模式，用于分析和规划

OpenCode 2 切换代理的默认按键是 Shift+Tab（2026-10-20 官方文档）。

OpenCode 2¶

OpenCode 2 是同一项目的另一个大版本。默认安装脚本仍然只安装 OpenCode 1；两个版本共用 opencode 命令，因此不能在该默认命令下并存（2026-10-20 官方安装脚本与迁移指南）。

安装 OpenCode 2¶

V2 文档 列出以下安装命令：

# OpenCode 2
curl -fsSL https://opencode.ai/v2/install | bash
npm install -g @opencode/cli
brew install anomalyco/tap/opencode-v2
bun install -g --trust @opencode/cli
pnpm add -g --allow-build=@opencode/cli @opencode/cli
yarn global add @opencode/cli

安装 V2 前，请先移除通过包管理器安装的 V1；V2 的 curl 安装脚本会替换 V1 二进制文件。如需升级已有的 OpenCode 1 安装，请运行 opencode upgrade --major（2026-10-20 官方文档）。

配置在 1 和 2 中都能用¶

OpenCode 2 从与 V1 相同的位置读取系统级、全局和项目配置，其中包括 ~/.config/opencode/opencode.json(c)。现有受支持的 V1 配置按设计继续可用；V1 配置格式仍然受支持，V2 原生格式是可选项。OpenCode 2 会在内存中规整受支持的 V1 与原生 V2 字段，不会改写源文件。迁移指南明确提醒：把文件转换为仅含原生 V2 的形状后，不要再让 V1 指向这些文件。

因此，上面的 provider / options.baseURL 配置在 OpenCode 1 和 OpenCode 2 中都能使用。如果只使用 OpenCode 2 并希望采用原生 V2 格式，相同的端点写法如下：

{
  "providers": {
    "anthropic": { "settings": { "baseURL": "https://api.qcode.cc/claude/v1" } },
    "openai": { "settings": { "baseURL": "https://api.qcode.cc/openai/v1" } }
  }
}

这种原生写法仅适用于 OpenCode 2。

影响上述配置的行为差异¶

• 项目外目录：V1 在访问项目外路径前会询问；V2 默认允许 external_directory。迁移指南没有说明 V2 如何处理上面 V1 格式配置里的 external_directory 规则（本页写的是 deny），请在 V2 中自行确认实际效果。在原生 V2 中，迁移指南保持 V1 行为的写法是一条 effect 为 ask 的 external_directory 规则。
• 权限动作：lsp 和 doom_loop 不是当前 V2 Core 的权限动作。
• 语言服务器：OpenCode 2 接受并保留 lsp 配置，但不运行语言服务器、不提供 LSP 工具，也不产出 LSP 诊断。
• 凭据：保存的 API Key 与 OAuth 令牌位于服务端的 SQLite 数据库。V2 在数据库迁移时会从旧的 auth.json 导入受支持的凭据；新增和更新的凭据写入 SQLite，不再写回该文件。
• 切换代理：agent.cycle 的默认按键是 Shift+Tab。
• 插件：V1 插件实现不能在 V2 中运行；插件使用新的插件 API。

qcode.cc 上关于 OpenCode 2 升级（含 1.19.1 会话共享下线）的说明见 OpenCode 2 升级与会话共享下线。

2.1.3–2.1.4 与 1.19.4 的变化（2026-10-26）¶

OpenCode 2.1.4 于 2026-10-23 发布，2.1.3 于 2026-10-22 发布，1.x 最新 1.19.4 于 2026-10-22 发布。与上面配置有关的条目如下：

• 2.1.3：自定义 provider 的 baseURL 设置现在会按预期覆盖目录里的模型端点（官方原句：“Custom provider baseURL settings now override catalog model endpoints as expected.”）。
• 2.1.3：内置 Bun 运行时升级到 1.4.4，包含 Brotli、TLS、HTTP/1.1、HTTP/2、HTTP/3、WebSocket 与 fetch 的安全修复，并更新根证书到 NSS 3.131.1。
• 2.1.4：MCP 服务器在工具调用中要求输入时，表单会弹出，而不是让调用一直等到超时；用 experimental.background_compaction 开启实验性的后台压缩。
• 1.19.4：1.x 线也获得了同一批 Bun 1.4.4 安全修复。

上面的 V2 安装命令在 2026-10-26 核对的文档里没有变化。

常见问题¶

API 连接失败¶

1. 检查 API 端点配置是否正确

2. 确认 API Key 已正确保存

3. 尝试切换到其他 API 端点（如 asia.qcode.cc / us）

4. 检查网络是否需要代理

模型不可用¶

确保在 opencode.json 中正确配置了模型定义，并且模型 ID 与 QCode 支持的模型名称一致。

oh-my-opencode 配置问题¶

参考官方文档：https://github.com/code-yeongyu/oh-my-openagent#configuration

相关链接¶

• OpenCode 官网

• OpenCode GitHub

• oh-my-opencode GitHub

• OpenCode 官方文档

下一步¶

• 查看 VS Code 集成 了解 IDE 内使用方式

• 探索 Codex 集成 使用 OpenAI Codex 模型

• 学习 CLI 技巧 提升终端效率

企业团队版 →