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

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 编程体验:

oh-my-opencode 界面

核心特性

  • 异步子代理 - 类似 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 端点选择

根据你的网络情况,可以修改配置中 providerbaseURL

端点 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/v1http://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 的 modelpromptpermission 配置。

步骤 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 后,可以通过以下方式验证配置是否成功:

# 启动 OpenCode
opencode

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

如果能正常对话,说明配置成功!

使用技巧

ultrawork 模式

如果安装了 oh-my-opencode,只需在提示词中加入 ultraworkulw,即可启用最强的并行多模型编排模式:

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

后台任务

使用 @ 语法调用专门的代理处理特定任务:

@oracle 帮我审查这段代码的架构设计
@librarian 查找类似功能的开源实现
@explore 搜索项目中所有的 API 端点

Tab 切换代理

Tab 键可以在 buildplan 代理之间切换:

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

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

常见问题

API 连接失败

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

  2. 确认 API Key 已正确保存

  3. 尝试切换到其他 API 端点(如深圳直连)

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

模型不可用

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

oh-my-opencode 配置问题

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

相关链接

下一步