# OpenCode 集成

> ⚠️ **重要提醒：需要开通 API 直接请求权限**
>
> 使用 OpenCode 需要开通 API 直接请求权限。由于直接调用 API 没有 Claude Code 的 session 机制，tokens 开销会比较大，因此该权限**默认关闭**。
>
> 如需开通，请联系在线客服或发送邮件至 **hi@qcode.cc**，我们会为您已购买的 API Key 开通该权限。

[OpenCode](https://github.com/anomalyco/opencode) 是一款 100% 开源的终端 AI 编程助手，类似于 Claude Code，但提供了更多的灵活性和自定义能力。它支持多模型切换、LSP 集成、TUI 界面，并且不绑定任何特定的 AI 服务商。

![OpenCode 界面截图](https://raw.githubusercontent.com/anomalyco/opencode/dev/packages/web/src/assets/lander/screenshot.png)

## 项目介绍

### OpenCode

[OpenCode](https://github.com/anomalyco/opencode) 是由 SST 团队开发的开源 AI 编程代理，主要特点包括：

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

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

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

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

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

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

**项目数据**（截至 2026 年 1 月）：

- GitHub Stars: 46.1k+

- 贡献者: 490+

- 版本: v1.0.223+

### oh-my-opencode

[oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode) 是 OpenCode 的增强插件，被称为"OpenCode 的类固醇"，提供了专业级的 AI 编程体验：

![oh-my-opencode 界面](https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/dev/.github/assets/omo.png)

**核心特性**：

- **异步子代理** - 类似 Claude Code 的并行任务处理能力

- **精选 Agent 配置** - 预配置的专业代理角色（Oracle、Librarian、Explore 等）

- **LSP/AST 工具** - 智能重构、代码分析、符号搜索等高级功能

- **Claude Code 兼容层** - 支持 Claude Code 的 hooks、commands、skills 配置

- **Sisyphus 主代理** - 基于 Claude Opus 4.8 的强大编排代理，支持后台并行任务

- **ultrawork 模式** - 只需在提示词中加入 `ultrawork`，自动启用最强并行模式

**内置代理角色**：

| 代理名称 | 模型 | 用途 |
|---------|------|------|
| **Sisyphus** | Claude Opus 4.8 | 主编排代理，规划和委派任务 |
| **Oracle** | GPT 5.4 | 架构设计、代码审查、策略分析 |
| **Librarian** | Claude Sonnet 4.6 | 多仓库分析、文档查阅、实现示例 |
| **Explore** | Grok Code | 快速代码库探索和模式匹配 |
| **Frontend UI/UX** | Gemini 2.5 Pro | 前端开发，擅长创建精美 UI |

## 安装配置

### 步骤 1：安装 OpenCode

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

**官方安装文档**：[https://opencode.ai/docs](https://opencode.ai/docs)

常用安装方式：

```bash
# 使用 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 提供了开箱即用的专业配置，强烈建议安装：

```bash
bunx oh-my-opencode install
```

**官方文档**：[https://github.com/code-yeongyu/oh-my-opencode](https://github.com/code-yeongyu/oh-my-opencode)

> **提示**：安装时会询问你拥有哪些 AI 订阅（Claude、ChatGPT、Gemini），根据实际情况选择即可。

### 步骤 3：配置 QCode API

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

> **关于模型选择**：下面的配置使用 QCode 提供的 Claude 5 系和 GPT Codex 系列。日常默认用 `claude-sonnet-5` / `claude-opus-5`；4.x 仍在售。QCode **在售 Gemini**（见 [qcode.cc/models](https://qcode.cc/models)），**不售卖 grok**。不要把「不卖 Gemini」写进配置说明。国产 id 见 [国产模型接入](/docs/usage/cn-models)。

> **关于 Google 服务商配置**：配置中的 `google` provider 块用于接入 Gemini（如 `gemini-2.5-pro`、`gemini-3.5-flash`）。请注意：官方 Gemini CLI 的 Pro/免费版已于 2026-06-18 停止维护（[Google 公告](https://developers.googleblog.com/an-important-update-transitioning-gemini-cli-to-antigravity-cli/)），后继为 **Google Antigravity CLI**；企业付费 Key 不受影响。如需使用 Google 模型工具链，建议改用 Antigravity CLI。

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

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

  "model": "anthropic/claude-opus-5",
  "small_model": "anthropic/claude-haiku-4-5",
  "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-5",
      "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 5",
      "model": "anthropic/claude-opus-5",
      "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.4",
      "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.3-Codex",
      "model": "openai/gpt-5.6-terra",
      "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",
      "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 5",
      "model": "anthropic/claude-sonnet-5",
      "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.4-Mini",
      "model": "openai/gpt-5.6-mini",
      "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://api.qcode.cc/claude/v1` | `https://api.qcode.cc/openai` | 全球用户，自动优选节点 |

> **大陆用户推荐**：使用 `asia.qcode.cc`（亚洲节点，HK/JP 就近）获得最佳速度，将 `baseURL` 改为 `https://asia.qcode.cc/claude/v1` 和 `https://asia.qcode.cc/openai`。

#### 可用模型

QCode 目前支持以下热门模型：

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

- `claude-opus-5` - 当前旗舰推理（`claude-opus-4-8` 仍在售）

- `claude-sonnet-5` - 日常默认平衡档（`claude-sonnet-4-6` 仍在售）

- `claude-haiku-4-5` - Haiku 4.5，极速响应

**OpenAI/Codex 系列**（路径：`/openai`）：

- `gpt-5.6-terra` - 编程/Codex CLI 推荐

- `gpt-5.6-sol` / `gpt-5.6-luna` - 5.6 同级变体

- `gpt-5.5` / `gpt-5.4` - 上一代，仍可用

- `gpt-5.6-mini` - 轻量/性价比

#### 配置说明

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

| Agent | 模型 | 模式 | 用途 |
|-------|------|------|------|
| **plan** | Claude Opus 5 | primary | 规划/拆解/技术方案（只读） |
| **build** | Claude Opus 5 | primary | 主力开发，端到端实现 |
| **codex** | GPT-5.4 | primary | 重构/迁移/大改动 |
| **review** | GPT-5.3-Codex | subagent | 代码审阅（只读） |
| **explore** | Claude Haiku 4.5 | subagent | 快速扫代码/定位文件（只读） |
| **general** | Claude Sonnet 5 | subagent | 通用研究/写说明（只读） |
| **think** | GPT-5.4-Mini | subagent | 辅助思考/推演边界条件（只读） |

你可以根据个人喜好调整各 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 后，可以通过以下方式验证配置是否成功：

```bash
# 启动 OpenCode
opencode

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

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

## 使用技巧

### ultrawork 模式

如果安装了 oh-my-opencode，只需在提示词中加入 `ultrawork` 或 `ulw`，即可启用最强的并行多模型编排模式：

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

### 后台任务

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

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

### Tab 切换代理

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

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

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

## 常见问题

### API 连接失败

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

2. 确认 API Key 已正确保存

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

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

### 模型不可用

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

### oh-my-opencode 配置问题

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

## 相关链接

- [OpenCode 官网](https://opencode.ai)

- [OpenCode GitHub](https://github.com/anomalyco/opencode)

- [oh-my-opencode GitHub](https://github.com/code-yeongyu/oh-my-opencode)

- [OpenCode 官方文档](https://opencode.ai/docs)

## 下一步

- 查看 [VS Code 集成](/docs/ide/vscode) 了解 IDE 内使用方式

- 探索 [Codex 集成](/docs/ide/codex) 使用 OpenAI Codex 模型

- 学习 [CLI 技巧](/docs/usage/cli-tips) 提升终端效率