OpenCode 接入 Claude API 完整配置指南：我是怎么把整套开发环境跑通的

OpenCode 接入 Claude API 完整配置指南：我是怎么把整套开发环境跑通的

这段时间我一直在折腾 OpenCode。最开始只是想找一个比传统 AI 聊天窗口更适合开发的工具，后来发现它其实已经不只是“聊天 AI”了，而是在往真正的 Coding Agent 方向走。它能读取项目结构、管理上下文、接管终端执行，甚至能配合不同模型完成复杂代码分析。

但很多人第一次安装 OpenCode 后，都会卡在同一个地方：模型怎么接？

尤其国内开发者，经常会遇到 API 连不上、模型列表为空、请求超时、流式输出中断等问题。网上教程又大多只写一句“填一下 Base URL 就行”，真正照着做的时候才发现根本没那么简单。

这篇文章我就不讲概念了，直接从我自己的实际配置过程出发，把 OpenCode 的两种接入方式完整走一遍，包括 GUI 图形界面配置、JSON 配置文件方案，以及 Windows、macOS、Linux 下的一些细节坑位。

OpenCode 到底支持哪种 API 接入方式

很多人第一次看到 OpenCode，会误以为它只能接官方 Anthropic API。实际上它支持的是 OpenAI-Compatible 风格接口，也就是说，只要你的 API 服务兼容标准请求结构，理论上都能接进去。

这一点其实非常重要。

因为很多开发者真正的问题并不是 OpenCode 本身，而是底层 API 环境。比如：

• 本地代理不稳定
• 终端环境不走系统代理
• 海外支付限制
• Anthropic Console 地区限制
• 长连接 SSE 被中途断开

所以现在不少开发者都会改成兼容接口方案，把模型层独立出来。

OpenCode 本身并不关心你后面接的是官方 Anthropic，还是别的兼容服务，它只负责按照标准 API 格式发请求。

我一开始用的是 GUI 图形界面配置

如果你第一次接 OpenCode，我建议先别碰 JSON 配置文件，直接走 GUI 配置最快。

打开 OpenCode 后，点击左下角设置按钮，进入 Provider 页面，然后新增一个自定义 Provider。

这里真正关键的字段其实只有三个：

比如很多兼容 Anthropic 的接口，都会要求 URL 最后带 /v1。

这一点非常容易漏。

很多人配置失败，其实不是 Key 错了，而是：

https://example.com

写成了这样，而不是：

https://example.com/v1

OpenCode 不会主动提醒你这个错误，结果就是模型列表空白或者请求直接失败。

配置完成之后，建议先只加一个模型测试，比如：

claude-sonnet-4-6

等确认能正常对话、流式输出正常，再继续添加其他模型。

因为很多时候真正的问题其实在 Provider 层，而不是模型层。

后来我为什么切到了配置文件模式

GUI 配置虽然方便，但我后来还是改成了 JSON 配置。

原因很简单：项目越来越多。

如果只是日常聊天，GUI 足够用了。但一旦开始：

• 多项目开发
• 远程服务器
• Docker 环境
• CI/CD
• 团队协作

你会发现配置文件才是更稳定的方案。

尤其项目级配置这个能力，真的很实用。

比如：

A 项目默认 Sonnet B 项目默认 Opus 测试环境自动切 Haiku

这种工作流，GUI 很难管理。

OpenCode 配置文件应该怎么写

macOS 和 Linux 默认路径：

~/.config/opencode/opencode.json

Windows：

%USERPROFILE%\.config\opencode\opencode.json

第一次没有目录的话，可以先创建：

mkdir -p ~/.config/opencode

然后写入配置：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "custom": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Custom Provider",
      "options": {
        "baseURL": "https://your-api-url/v1",
        "apiKey": "{env:OPENCODE_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "claude-opus-4-7": {
          "name": "Claude Opus 4.7"
        }
      }
    }
  },
  "model": "custom/claude-sonnet-4-6"
}

这里有个我后来才意识到的问题：不要把 API Key 写死在 JSON 里。

因为你迟早会：

• 提交 Git
• 远程同步
• 做团队协作
• 上传配置仓库

Key 写死基本等于主动泄露。

环境变量为什么一定要配

这是我后来吃过亏才真正重视的事情。

macOS / Linux：

export OPENCODE_API_KEY="sk-xxx"

永久生效：

echo 'export OPENCODE_API_KEY="sk-xxx"' >> ~/.zshrc
source ~/.zshrc

Windows：

$env:OPENCODE_API_KEY="sk-xxx"

永久环境变量：

[Environment]::SetEnvironmentVariable(
  "OPENCODE_API_KEY",
  "sk-xxx",
  "User"
)

这样最大的好处，是所有工具都能共用。

包括：

• OpenCode
• Claude Code
• Python SDK
• Node.js SDK
• 本地 Agent

后期维护会轻松很多。

我现在怎么选模型

很多人接进去之后，第一反应都是：

“到底哪个模型最适合 Coding？”

其实没有绝对答案。

如果只是日常开发，比如：

• React
• Vue
• Python
• API 开发
• Bug 修复

Sonnet 基本已经够用了。

如果开始涉及：

• 大型代码库
• 多文件重构
• Agent 推理
• 长上下文分析
• 自动化架构修改

再考虑 Opus。

Haiku 更偏轻量场景，比如：

• 批量补全
• 自动化脚本
• 快速响应任务

真正长期开发之后，你会发现模型选择其实是“成本、速度、推理能力”之间的平衡，而不是越贵越好。

最后几个特别容易踩的坑

第一个坑，是 Base URL 少写 /v1。

这个真的太常见了。

第二个坑，是 Windows 用户直接照抄 Linux 路径。

Windows 下 ~/.config 不一定生效。

第三个坑，是很多人以为 OpenCode 卡顿是软件问题。

实际上很多时候是：

• SSE 被代理缓冲
• 长连接超时
• 反向代理没关 buffering
• API 提供方流式支持不完整

第四个坑，是模型名写错。

OpenCode 不会帮你自动纠错，模型 ID 必须和后端真实模型名一致。

最后一个坑，是很多开发者一开始就疯狂堆模型。

实际上真正稳定的工作流，往往只有一两个主力模型长期使用。先把链路稳定、上下文管理、流式输出跑顺，比盲目堆模型重要得多。