OpenCode 安装教程（macOS）

本页指导你在 macOS 上安装 OpenCode，并配置通过 AI通道 调用 Claude / GPT 模型。

0. 前置：安装 Node.js

node --version

低于 v22.0.0 请先查阅 Node.js macOS 安装指南 升级。

1. 安装 OpenCode

npm i -g opencode-ai@latest
opencode --version

若遇到 EACCES 权限问题，建议使用 nvm 管理的 Node，或改用 sudo。

2. 安装 SDK 依赖（必须）

2.1 什么是 SDK

OpenCode 运行时会从配置目录加载 Vercel AI SDK 的 provider 包——用 Claude 就装 @ai-sdk/anthropic，用 GPT 就装 @ai-sdk/openai。没有装对应 SDK，启动会直接报错。

2.2 安装 Claude SDK（推荐）

mkdir -p ~/.config/opencode
cd ~/.config/opencode
npm install @ai-sdk/anthropic

2.3 可选：安装 OpenAI SDK

npm install @ai-sdk/openai

3. 配置 OpenCode（接入 AI通道）

3.1 配置文件在哪里

~/.config/opencode/opencode.json

3.2 获取 AI通道 Key

登录 aitongdao.com → 令牌菜单 → 创建令牌，Claude 模型选 claude 或 ccmax 分组，GPT 模型选 codex 分组。

3.3 写入配置文件

cat > ~/.config/opencode/opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "sk-你的密钥",
        "baseURL": "https://aitongdao.com"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" },
        "claude-opus-4-6": { "name": "Claude Opus 4.6" }
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}
EOF

要点：Anthropic 协议的 baseURL 是 https://aitongdao.com，没有 /v1 后缀；model 字段使用 provider/model-id 的形式。

3.4 如果想同时配置 GPT 模型

在 provider 对象下追加 openai 分支，OpenAI 协议的 base URL 带 /v1：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "apiKey": "sk-你的密钥",
        "baseURL": "https://aitongdao.com"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6" }
      }
    },
    "openai": {
      "options": {
        "apiKey": "sk-你的密钥",
        "baseURL": "https://ai.aitongdao.com/v1"
      },
      "models": {
        "gpt-5": { "name": "GPT-5" }
      }
    }
  },
  "model": "anthropic/claude-sonnet-4-6"
}

4. 启动并验证

opencode

进入会话后 /models 查看模型列表，选中后发送测试消息。

常见问题

• opencode 命令找不到：确认 npm 全局 bin 目录在 $PATH，或重新打开终端窗口。
• 启动报 Cannot find module '@ai-sdk/...'：provider 包没装在 ~/.config/opencode 目录下，cd 到该目录重新 npm install。
• 配置写入失败：确认 ~/.config/opencode/ 目录已存在且有写权限；macOS 新装 zsh 时该目录可能不存在。
• 调用 Claude 模型 404：多半是 baseURL 错误加了 /v1，Anthropic 协议不需要 /v1。
• 调用 GPT 模型 404：相反地，OpenAI 协议的 baseURL 必须带 /v1。