最近更新：2026年3月18日 06:55

OpenCode 配置指南

适用场景：希望在终端中使用 OpenCode，并通过 NextAI Code 接入 GPT、Claude、Gemini 等模型的用户。

你会得到什么：

OpenCode 的安装方法

NextAI Code 的配置方式

GPT / Claude / Gemini 三类模型的正确写法

一份可直接照抄的最小可用配置

常见报错排查方法

0. OpenCode 和 Claude Code CLI / Codex CLI 有什么区别

如果你已经用过 Claude Code CLI、Codex CLI、Gemini CLI，最容易产生的疑问就是：

既然这些官方 CLI 都能用，为什么还要单独看 OpenCode？

核心区别不是“能不能调用模型”，而是：

Claude Code CLI / Codex CLI / Gemini CLI：更像是单一模型厂商推出的官方客户端
OpenCode：更像是一个统一的 AI 编码工作台 / 终端容器

0.1 一句话理解

Claude Code CLI：最适合把 Anthropic 生态用到最深
Codex CLI：最适合把 OpenAI / Codex 生态用到最深
Gemini CLI：最适合直接使用 Google / Gemini 生态
OpenCode：最适合 在一个终端工具里统一接入 GPT / Claude / Gemini，并按需要切换 provider、模型和编排方式

0.2 一眼看懂：OpenCode 和官方 CLI 怎么选

如果你不想先读长解释，直接看下面这版就够了。

Claude Code CLI

最适合谁：主要用 Claude 的用户
核心优势：Anthropic 官方体验完整，Claude 工作流最原生
局限：更偏单一模型生态，多模型统一管理不如 OpenCode
适不适合 NextAI Code：适合，但更适合“主要用 Claude”

Codex CLI

最适合谁：主要用 GPT / Codex 的用户
核心优势：OpenAI 官方体验完整，代码任务上手直接
局限：更偏 OpenAI 自家工作流，不适合统一管理多模型
适不适合 NextAI Code：适合，但更适合“主要用 GPT / Codex”

Gemini CLI

最适合谁：主要用 Gemini 的用户
核心优势：Gemini 原生体验直接，多模态场景自然
局限：更偏 Google 生态，不适合统一管理多模型
适不适合 NextAI Code：适合，但更适合“主要用 Gemini”

OpenCode

最适合谁：想统一接入多模型的用户
核心优势：同一工具里统一接 GPT / Claude / Gemini，后续还能叠加插件和路由
局限：初次配置比单一官方 CLI 多一步
适不适合 NextAI Code：最适合想通过 NextAI Code 长期统一使用多模型的人

如果你只打算长期深用某一家模型，官方 CLI 通常更直接。如果你想把 GPT / Claude / Gemini 都放进同一个终端工作流，OpenCode 会更合适。

为了方便快速决策，你也可以直接记这句：

只深用单一模型 → 优先官方 CLI；想统一接入多模型并长期扩展 → 优先 OpenCode。

0.3 OpenCode 强在哪里

1）它不是绑定单一模型厂商

Claude Code CLI、Codex CLI、Gemini CLI 本质上都更偏向各自厂商自己的工作流。

而 OpenCode 的优势是：

可以同时接 GPT、Claude、Gemini
可以统一走 NextAI Code
可以在同一套配置里管理多个 provider 和多个模型
后面还可以叠加 oh-my-opencode 做 agent / category 路由

如果你的目标不是“只用某一家”，而是：

哪个模型适合就用哪个
想把不同模型放进同一个工作流
想统一 Key、统一入口、统一切换方式

那 OpenCode 会更顺手。

2）它更像一个可扩展底座，不只是单个 CLI

官方 CLI 通常更强调“把自家模型用好”。

OpenCode 更强调的是：

provider 抽象
model 抽象
tools 抽象
plugin / orchestration 扩展

这意味着它更适合下面这些场景：

先用最小配置跑通 GPT
再补 Claude
再补 Gemini
再往上叠路由、编排、插件

也就是说，它更像一个可以逐层增强的底座。

3）对 NextAI Code 这种聚合网关更友好

如果你只是对接单一官方 API，用官方 CLI 往往最直接。

但如果你用的是 NextAI Code 这类统一网关，OpenCode 的优势会更明显：

同一个入口同时接多家模型
配置结构更统一
更容易把 GPT / Claude / Gemini 放到一个文档里讲清楚
更容易把“主配置”和“路由层”分开

对于帮助中心文档来说，这种统一抽象也更好写、更好教。

4）适合需要“多模型协作”的人

如果你的诉求只是：

我就想稳定用 Claude 写代码
我就想直接用 Codex
我就想原生用 Gemini

那直接用对应官方 CLI 没问题。

但如果你的诉求变成：

编码想用 GPT / Codex
分析和推理想用 Claude
看图、多模态想用 Gemini
以后可能还要上 agent 路由

那 OpenCode 会更强，因为它天然适合做这层整合。

0.4 哪些人更适合直接选 OpenCode

更适合选 OpenCode 的情况：

你想在一个工具里统一使用 GPT / Claude / Gemini
你希望所有模型都走 NextAI Code 统一接入
你希望后续能扩展到 oh-my-opencode 这类路由层
你不想每换一个模型就换一套 CLI 和配置方式
你希望一套文档、一套配置思路长期复用

0.5 什么时候不一定要用 OpenCode

下面这些情况，直接用官方 CLI 也完全合理：

只用 Claude，那就直接用 Claude Code CLI
只用 OpenAI / Codex，那就直接用 Codex CLI
只用 Gemini，那就直接用 Gemini CLI
你的目标只是“今天先把某一个模型快速跑起来”

所以 OpenCode 的价值，不在于“它一定比官方 CLI 更强”，而在于：

当你需要统一接入、多模型切换、后续扩展编排能力时，OpenCode 更像长期方案。

1. 安装 OpenCode

先安装 OpenCode：

npm install -g opencode-ai

安装完成后，检查是否成功：

opencode --help

如果能正常输出帮助信息，说明安装成功。

如果你的环境里 opencode 命令还没进 PATH，通常重新打开一个终端窗口即可。

2. 在 NextAI Code 创建 API Key

打开 NextAI Code 控制台 - 令牌管理
新建一个令牌
建议设置：
- 名称：例如 opencode
- 过期时间：建议选 永不过期
- 额度：按你的预算设置
- IP 白名单：没有固定出口时先留空
复制生成的 sk- 开头令牌

如果你后面准备分别给 GPT / Claude / Gemini 配不同分组，也可以为不同用途创建不同 token。

3. OpenCode 配置文件放哪里

OpenCode 的主配置文件通常是：

~/.config/opencode/opencode.json

如果目录不存在，可以先创建：

mkdir -p ~/.config/opencode

然后新建配置文件：

touch ~/.config/opencode/opencode.json

4. 最小可用配置（推荐先跑通这个）

先不要一上来就配很多 provider。
先用一份最小配置跑通，再逐步加模型。

下面是一份可以直接照着改的最小可用示例：

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "permission": "allow",
  "provider": {
    "nextai": {
      "name": "NextAI GPT",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "你的NextAI Code令牌",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4"
        }
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "glob": true,
    "grep": true,
    "read": true,
    "write": true
  }
}

这份配置里最重要的 4 个点

1）`apiKey`

填你在 NextAI Code 控制台创建的 token：

"apiKey": "sk-xxxxxxxx"

2）`baseURL`

如果你走的是 OpenAI-compatible 协议，要写：

"baseURL": "https://www.nextai-code.com/v1"

注意这里 必须带 /v1。

3）`models`

这里声明 OpenCode 可以使用的模型。

4）`tools`

如果你希望 OpenCode 能读写文件、搜索代码、执行命令，建议把这些工具打开。

5. GPT / Claude / Gemini 分别怎么配

这一部分是最容易写错的。

核心原则就一句话：

GPT 类模型 → 一般走 OpenAI-compatible
Claude 类模型 → 一般走 Anthropic 协议
Gemini 类模型 → 一般走 Google 协议

5.1 配 GPT（推荐）

这是最常见、也最稳的一种写法：

{
  "provider": {
    "nextai-openai": {
      "name": "NextAI GPT",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4"
        },
        "gpt-5.3-codex": {
          "id": "gpt-5.3-codex",
          "name": "GPT-5.3-Codex"
        }
      }
    }
  }
}

5.2 配 Claude

Claude 通常走 Anthropic 协议：

{
  "provider": {
    "nextai-anthropic": {
      "name": "NextAI Claude",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "claude-sonnet-4.6": {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6"
        },
        "claude-opus-4.6": {
          "id": "claude-opus-4-6",
          "name": "Claude Opus 4.6"
        }
      }
    }
  }
}

5.3 配 Gemini

Gemini 通常走 Google 协议：

{
  "provider": {
    "nextai-gemini": {
      "name": "NextAI Gemini",
      "npm": "@ai-sdk/google",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gemini-3.1": {
          "id": "gemini-3.1-pro-high",
          "name": "Gemini 3.1 Pro High"
        }
      }
    }
  }
}

不同客户端对 Gemini 的支持方式可能有差异。
如果你发现某个 Gemini 模型名报错，优先检查：模型 id 是否与 NextAI Code 当前支持的一致。

6. 推荐的完整配置示例

如果你希望一次性把 GPT / Claude / Gemini 都配好，可以参考下面这个结构：

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "permission": "allow",
  "plugin": [],
  "provider": {
    "nextai-openai": {
      "name": "NextAI GPT",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4"
        },
        "gpt-5.3-codex": {
          "id": "gpt-5.3-codex",
          "name": "GPT-5.3-Codex"
        }
      }
    },
    "nextai-anthropic": {
      "name": "NextAI Claude",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "claude-sonnet-4.6": {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6"
        }
      }
    },
    "nextai-gemini": {
      "name": "NextAI Gemini",
      "npm": "@ai-sdk/google",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gemini-3.1": {
          "id": "gemini-3.1-pro-high",
          "name": "Gemini 3.1 Pro High"
        }
      }
    }
  },
  "tools": {
    "bash": true,
    "edit": true,
    "glob": true,
    "grep": true,
    "read": true,
    "write": true
  }
}

这份配置的好处是：

结构清晰
后续加模型简单
一眼能分清不同协议

7. 进阶：如果你要用 oh-my-opencode

oh-my-opencode 不是 OpenCode 的 provider。它是一个额外的编排 / 路由层插件，用来把不同 agent、不同任务类别分配给不同模型。

一句话理解：

opencode.json：负责 provider、API key、模型定义、插件启用
oh-my-opencode.json / jsonc：负责 agent / category → 具体模型 的路由策略

如果你只是想先把 OpenCode 跑起来，可以先跳过这一节。如果你想做多 agent 编排，再继续往下配。

7.1 先安装 / 启用插件

先确保你已经装好了 OpenCode：

npm install -g opencode-ai

然后编辑主配置文件：

~/.config/opencode/opencode.json

在 plugin 里启用 oh-my-opencode：

{
  "$schema": "https://opencode.ai/config.json",
  "autoupdate": true,
  "permission": "allow",
  "plugin": [
    "oh-my-opencode@latest"
  ],
  "provider": {
    "nextai-openai": {
      "name": "NextAI GPT",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gpt-5.3-codex": {
          "id": "gpt-5.3-codex",
          "name": "GPT-5.3-Codex"
        },
        "gpt-5.4": {
          "id": "gpt-5.4",
          "name": "GPT-5.4"
        }
      }
    },
    "nextai-anthropic": {
      "name": "NextAI Claude",
      "npm": "@ai-sdk/anthropic",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "claude-sonnet-4.6": {
          "id": "claude-sonnet-4-6",
          "name": "Claude Sonnet 4.6"
        }
      }
    },
    "nextai-gemini": {
      "name": "NextAI Gemini",
      "npm": "@ai-sdk/google",
      "options": {
        "apiKey": "你的API密钥",
        "baseURL": "https://www.nextai-code.com/v1"
      },
      "models": {
        "gemini-3.1": {
          "id": "gemini-3.1-pro-high",
          "name": "Gemini 3.1 Pro High"
        }
      }
    }
  }
}

先把主配置跑通，再继续配 oh-my-opencode。
不要一开始就同时排查 provider 问题和路由问题。

7.2 再创建 oh-my-opencode 的独立配置文件

推荐路径：

~/.config/opencode/oh-my-opencode.json

如果你想加注释，也可以用：

~/.config/opencode/oh-my-opencode.jsonc

建议先创建：

mkdir -p ~/.config/opencode
touch ~/.config/opencode/oh-my-opencode.json

然后写入配置。

7.3 一个可直接照抄的 NextAI Code 示例

下面这份示例只围绕 NextAI Code 展开，不引入其他 provider，也不写多套切换逻辑。

{
  "$schema": "https://raw.githubusercontent.com/code-yeongyu/oh-my-opencode/master/assets/oh-my-opencode.schema.json",
  "agents": {
    "hephaestus": {
      "model": "nextai-openai/gpt-5.3-codex",
      "variant": "medium"
    },
    "oracle": {
      "model": "nextai-anthropic/claude-sonnet-4.6",
      "variant": "high"
    },
    "multimodal-looker": {
      "model": "nextai-gemini/gemini-3.1"
    },
    "prometheus": {
      "model": "nextai-anthropic/claude-sonnet-4.6",
      "variant": "max"
    },
    "sisyphus": {
      "model": "nextai-anthropic/claude-sonnet-4.6",
      "variant": "max"
    }
  },
  "categories": {
    "deep": {
      "model": "nextai-anthropic/claude-sonnet-4.6",
      "variant": "high"
    },
    "quick": {
      "model": "nextai-openai/gpt-5.3-codex"
    },
    "visual-engineering": {
      "model": "nextai-gemini/gemini-3.1"
    },
    "writing": {
      "model": "nextai-gemini/gemini-3.1"
    },
    "ultrabrain": {
      "model": "nextai-anthropic/claude-sonnet-4.6",
      "variant": "max"
    }
  }
}

这份配置表达的意思是：

hephaestus：偏执行型编码，走 GPT / Codex
oracle：偏分析 / 推理，走 Claude
multimodal-looker：偏看图 / 多模态，走 Gemini
deep：复杂任务优先给更强推理模型
quick：小修改、小修复交给更快的模型
visual-engineering：前端 / UI / 视觉相关交给 Gemini

如果你是第一次接触 oh-my-opencode，建议先照着这份最小路由示例跑通，再按自己的习惯微调。

7.4 常见误区

误区 1：把 `agents` / `categories` 直接写进 `opencode.json`

不推荐。

更稳的方式是：

opencode.json 只管主配置和 plugin
oh-my-opencode.json / jsonc 只管路由

这样排错最清楚。

误区 2：provider 名和 model 引用名对不上

例如你在主配置里写的是：

"nextai-openai": { ... }

那在 oh-my-opencode 里就应该引用：

"nextai-openai/gpt-5.3-codex"

前半段必须和 provider 里的 key 对上。

误区 3：主配置没跑通就开始怀疑 oh-my-opencode

先确认这三层：

OpenCode 能正常启动
provider 能正常调用模型
再看 oh-my-opencode 路由是否正确

否则会把两个问题混在一起。

8. 如何验证配置是否成功

配置完成后，建议按下面顺序检查。

第一步：检查主配置是否存在

ls -la ~/.config/opencode/opencode.json

如果你启用了 oh-my-opencode，再检查它的独立配置：

ls -la ~/.config/opencode/oh-my-opencode.json

或者：

ls -la ~/.config/opencode/oh-my-opencode.jsonc

第二步：检查 OpenCode 是否能启动

opencode --help

如果这里都起不来，先不要查路由层。

第三步：确认主配置里的 plugin 已启用

直接打开或打印 opencode.json，确认有这一项：

"plugin": [
  "oh-my-opencode@latest"
]

第四步：确认 `oh-my-opencode` 里的模型引用和 provider key 对得上

例如你在主配置里用的是：

"nextai-openai": { ... }

那么 oh-my-opencode 里就应该写：

"model": "nextai-openai/gpt-5.3-codex"

如果前缀写错，路由一定不会按预期工作。

第五步：实际发起一次任务验证

先发一个简单任务，例如：

写一个 hello world

然后再试一个更像多 agent 路由的任务，例如：

分析这个页面的 UI 问题并给出修改建议

如果能够正常返回，并且符合你预期的模型 / agent 分工，就说明配置基本生效。

9. 常见问题

OpenCode 启动失败，提示配置错误？

优先检查这几项：

opencode.json 是否是合法 JSON
末尾是否多了逗号
provider、models 层级是否写错
apiKey 是否漏填

GPT 模型调用失败？

重点检查：

npm 是否使用 @ai-sdk/openai-compatible
baseURL 是否写成了 https://www.nextai-code.com/v1
模型 id 是否正确

Claude 模型调用失败？

先确认：

是否使用了 @ai-sdk/anthropic
模型 id 是否写对，例如 claude-sonnet-4-6
token 是否有对应分组权限

Gemini 模型调用失败？