词源探索

外观

OpenCode 配置指南 ​

最近更新：2026 年 10 月 17 日（Asia/Shanghai）

关联：帮助中心 · Claude Code · Codex · Gemini CLI

OpenCode 是面向终端的多模型编码工作台：可在同一工具里接入 Claude、Gemini、Kimi 等，而不仅限于单一厂商官方 CLI。

工具更适合
Claude Code / Codex / Gemini CLI深耕单一官方生态
OpenCode统一管理多厂商、后续扩展路由与插件

1. 安装 ​

bash
npm install -g opencode-ai
opencode --help

命令不在 PATH 时，重开一个终端窗口。

2. 创建令牌 ​

控制台「令牌管理」新建令牌（如 opencode），复制 sk- 密钥。若打算按协议拆分额度，可为 OpenAI 兼容 / Anthropic / Gemini 各建一个令牌。

3. 配置文件位置 ​

bash
mkdir -p ~/.config/opencode
# 主配置
touch ~/.config/opencode/opencode.json

路径：~/.config/opencode/opencode.json。

4. 最小可用配置（先跑通一个） ​

json
{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "permission": "allow",
  "provider": {
    "ciyuan": {
      "name": "词源探索",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net/v1"
      },
      "models": {
        "claude-sonnet-4-6": {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6"
        }
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "glob": true,
    "grep": true,
    "read": true,
    "write": true
  }
}

要点：

  1. apiKey：词源探索令牌
  2. baseURL：OpenAI 兼容路径，必须带 /v1
  3. models.*.id：与平台模型 ID 完全一致
  4. tools：需要改文件 / 跑命令时保持开启

先只配一个模型，确认能对话后再加厂商。

5. 按协议拆分 Provider ​

OpenAI 兼容（Claude / Gemini / Kimi 等均可先走这条） ​

json
{
  "provider": {
    "ciyuan-openai": {
      "name": "词源探索 · OpenAI 兼容",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net/v1"
      },
      "models": {
        "claude-sonnet-4-6": {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
        "gemini-3.1-pro": {"id": "gemini-3.1-pro", "name": "Gemini 3.1 Pro"},
        "kimi-k3": {"id": "kimi-k3", "name": "Kimi K3"},
        "deepseek-v4-flash": {"id": "deepseek-v4-flash", "name": "DeepSeek V4 Flash"}
      }
    }
  }
}

Anthropic 协议（Claude 原生） ​

json
{
  "provider": {
    "ciyuan-anthropic": {
      "name": "词源探索 · Anthropic",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net"
      },
      "models": {
        "claude-sonnet-4-6": {"id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6"},
        "claude-opus-4-8": {"id": "claude-opus-4-8", "name": "Claude Opus 4.8"}
      }
    }
  }
}

Anthropic SDK 风格的 baseURL 通常不带 /v1；若你使用的 OpenCode / AI SDK 版本要求带 /v1，以实际报错为准试两种写法。

Google 协议（Gemini） ​

json
{
  "provider": {
    "ciyuan-gemini": {
      "name": "词源探索 · Gemini",
      "npm": "@ai-sdk/google",
      "options": {
        "apiKey": "sk-xxxxxxxx",
        "baseURL": "https://ai.afp.net"
      },
      "models": {
        "gemini-3.1-pro": {"id": "gemini-3.1-pro", "name": "Gemini 3.1 Pro"},
        "gemini-3.5-flash": {"id": "gemini-3.5-flash", "name": "Gemini 3.5 Flash"}
      }
    }
  }
}

Gemini 的 baseURL 是否附带 /v1beta 取决于 SDK；接词源探索时一般填网关根地址，由兼容层拼接。模型 ID 必须与 /v1/models 一致。

6. 验证顺序 ​

  1. ls ~/.config/opencode/opencode.json 确认文件存在且为合法 JSON（无尾逗号）。
  2. opencode --help 能启动。
  3. 发起简单任务（如「写一个 hello world」）。
  4. 再加入第二个 provider / 模型。

7. 关于 oh-my-opencode（可选） ​

oh-my-opencode 是编排/路由插件，不是 provider。建议：

  • opencode.json：只管 provider、Key、模型、是否启用 plugin
  • oh-my-opencode.json：管 agent / category → provider/model 路由

仅在主配置已跑通后再启用。引用名必须与 provider 键一致，例如主配置为 ciyuan-openai，路由里写 ciyuan-openai/claude-sonnet-4-6。

8. 故障排查 ​

现象处理
配置解析失败检查 JSON 语法与层级
OpenAI 兼容调用失败baseURL 是否含 /v1；npm 是否为 @ai-sdk/openai-compatible
Claude 原生失败是否用 @ai-sdk/anthropic；模型 ID；Base URL 带/不带 /v1
Gemini 失败是否用 @ai-sdk/google；勿把 GPT 专用字段硬套过来
模型不存在对照 /v1/models 与令牌分组

9. 推荐实践 ​

  1. 安装 OpenCode
  2. 创建词源探索令牌
  3. 先写最小配置，只挂一个模型
  4. 跑通后再加 Claude 原生 / Gemini
  5. 最后才考虑路由插件

返回：帮助中心