← Windows下OpenCode的安装与配置

Windows下OpenCode的安装与配置（二）——配置与模型接入

Windows下OpenCode的安装与配置 2026-04-16 2 0
OpenCode AI API 配置 教程

上一篇把 OpenCode 装好了，但它现在还是个空壳——没有配置 AI 模型，什么都干不了。这一篇就来解决这个问题：写配置文件、接模型、让它真正能跟你对话。

opencode.json 在哪

OpenCode 的所有配置都写在一个 opencode.json 文件里。它有两个可能的位置：

  • 全局配置：C:\Users\你的用户名\.config\opencode\opencode.json
  • 项目级配置：项目根目录下的 opencode.json

项目级配置会覆盖全局配置。如果你只是想全局统一用一套模型，直接改全局配置就够了。

如果这个文件还不存在，手动创建一个就行：

# 确保目录存在
mkdir "$env:USERPROFILE\.config\opencode" -Force

# 创建空配置文件
New-Item "$env:USERPROFILE\.config\opencode\opencode.json" -ItemType File

配置文件的基本结构

先看一个最小可用的配置，你就知道整体结构长什么样了：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "anthropic",
      "options": {
        "apiKey": "你的 Anthropic API Key"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

这个配置做了三件事：

  1. 声明 $schema，让编辑器能提供自动补全和校验
  2. 在 provider 里注册了一个 Anthropic 提供商
  3. 在提供商下面声明了一个可用的模型

有了这三样，OpenCode 就能用了。下面逐步拆开讲。

接入 Anthropic（Claude 系列）

如果你有 Anthropic 官方的 API Key，配置非常直接：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "anthropic",
      "options": {
        "apiKey": "sk-ant-xxxxx-你的key"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-opus-4-20250514": {
          "name": "Claude Opus 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

几个要点：

  • npm 字段指定 AI SDK 的 npm 包名，Anthropic 对应 @ai-sdk/anthropic
  • apiKey 填你自己的 Key
  • models 里每个 Key 是模型的 ID（要跟 Anthropic API 的模型名一致），name 是你给它起的显示名称
  • limit.context 是上下文窗口大小，limit.output 是最大输出长度

接入 OpenAI（GPT 系列）

OpenAI 的配置方式几乎一样，换个 npm 包和 Key 就行：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "openai",
      "options": {
        "apiKey": "sk-xxxxx-你的key"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o",
          "limit": { "context": 128000, "output": 16384 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        },
        "o3": {
          "name": "o3",
          "limit": { "context": 200000, "output": 100000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] }
        }
      }
    }
  }
}

提示：OpenAI 和 Anthropic 可以同时配。两个 provider 写在同一个 provider 对象里就行，启动 OpenCode 后可以随时切换模型。

接入第三方中转站（国内用户推荐）

如果你在国内，直连 Anthropic 和 OpenAI 的官方 API 会很不稳定，甚至可能直接连不上。这时候用第三方中转站是更现实的选择。

中转站的配置方式和官方几乎一样，唯一的区别是多一个 baseURL 字段。以 Anthropic 走中转为例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "anthropic",
      "options": {
        "baseURL": "https://你的中转站地址/api/v1",
        "apiKey": "你的中转站 API Key"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

OpenAI 走中转同理：

"openai": {
  "npm": "@ai-sdk/openai",
  "name": "openai",
  "options": {
    "baseURL": "https://你的中转站地址/v1",
    "apiKey": "你的中转站 API Key"
  },
  "models": {
    "gpt-4o": {
      "name": "GPT-4o",
      "limit": { "context": 128000, "output": 16384 },
      "modalities": { "input": ["text", "image"], "output": ["text"] }
    }
  }
}

提示：不同中转站的 baseURL 格式可能不同，有的结尾要加 /v1，有的不用。拿不准的话看中转站的文档，或者直接问客服。

多 Provider 完整配置示例

实际使用中，你大概率会同时配多个 Provider。比如 Anthropic 用中转，OpenAI 也用中转，这样你就能在 Claude 和 GPT 之间自由切换。完整示例如下：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "openai": {
      "npm": "@ai-sdk/openai",
      "name": "openai",
      "options": {
        "baseURL": "https://你的中转站地址/v1",
        "apiKey": "你的 OpenAI 中转 Key"
      },
      "models": {
        "gpt-4o": {
          "name": "GPT-4o",
          "modalities": {
            "input": ["text", "image"],
            "output": ["text"]
          },
          "limit": {
            "context": 128000,
            "output": 16384
          }
        }
      }
    },
    "anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "anthropic",
      "options": {
        "baseURL": "https://你的中转站地址/api/v1",
        "apiKey": "你的 Anthropic 中转 Key"
      },
      "models": {
        "claude-sonnet-4-20250514": {
          "name": "Claude Sonnet 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        },
        "claude-opus-4-20250514": {
          "name": "Claude Opus 4",
          "limit": { "context": 200000, "output": 64000 },
          "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] }
        }
      }
    }
  }
}

模型的高级配置选项

除了基本的 limit 和 modalities，模型还支持一些进阶配置。

Thinking Budget（思考预算）

Claude 系列支持通过 thinkingConfig 控制模型的思考深度。思考预算越大，模型会花更多 token 来"想"，输出质量通常更高，但也更贵更慢：

"claude-opus-4-20250514": {
  "name": "Claude Opus 4",
  "limit": { "context": 200000, "output": 64000 },
  "modalities": { "input": ["text", "image", "pdf"], "output": ["text"] },
  "variants": {
    "low": { "thinkingConfig": { "thinkingBudget": 8192 } },
    "max": { "thinkingConfig": { "thinkingBudget": 32768 } }
  }
}

variants 会在 OpenCode 里生成模型变体，你可以在不同场景选不同的思考深度。

OpenAI 推理参数

GPT 系列可以通过 options 配置推理参数：

"gpt-4o": {
  "name": "GPT-4o",
  "limit": { "context": 128000, "output": 16384 },
  "modalities": { "input": ["text", "image"], "output": ["text"] },
  "options": {
    "store": false,
    "reasoningEffort": "high"
  }
}
  • store: false 表示不在 OpenAI 端存储对话记录
  • reasoningEffort 控制推理强度，可选 low、medium、high

验证配置

配置写好后，保存文件，然后在终端启动 OpenCode：

opencode

如果配置正确，你会进入 TUI 界面，并且在底部看到可用的模型列表。

你也可以用命令查看已配置的模型：

opencode models

这条命令会列出你在配置文件里声明的所有模型。如果列表为空或报错，说明 opencode.json 有问题，回去检查一下 JSON 格式是否正确。

常见问题：JSON 不允许注释。如果你在配置文件里写了 // 开头的注释，OpenCode 可能会报解析错误。要写注释的话，可以把配置文件改为 opencode.jsonc（部分版本支持），或者干脆不写注释，把说明记在别的地方。

启动并试用

进入任意一个你想让 AI 帮忙的项目目录，然后启动：

cd D:\你的项目目录
opencode

OpenCode 会自动扫描项目结构，然后你就可以开始跟 AI 对话了。试着输入一些简单的指令感受一下：

  • 这个项目是做什么的？ — 让 AI 理解项目
  • 帮我看看 src/main.ts 有什么问题 — 代码审查
  • 写一个单元测试 — 代码生成
  • 运行 npm test — 执行命令

在 TUI 界面里，你可以用快捷键切换模型。按 Ctrl+K 打开命令面板，里面能看到所有可用操作。

小结

这一篇完成了：

  1. 配置文件结构 — 理解 opencode.json 的组织方式
  2. 接入 Anthropic — Claude 系列模型配置
  3. 接入 OpenAI — GPT 系列模型配置
  4. 接入第三方中转站 — 国内用户的实际方案
  5. 高级模型参数 — Thinking Budget 和推理配置
  6. 验证与试用 — 确认配置生效

现在 OpenCode 已经是一个能正常对话的 AI 助手了。但它还只是"单兵作战"。下一篇会安装 Oh My OpenCode 插件，让它变成一个多智能体协作系统，再装一批 Skills 让 AI 在特定领域更专业。

目录

Comments (0)

No comments yet. Be the first!