OpenCode 配置 API 教程：151k Stars 的终端编程 Agent，怎么接上自己的模型

title: OpenCode 配置 API 教程：151k Stars 的终端编程 Agent，怎么接上自己的模型
date: 2026-04-29
keywords: OpenCode, OpenCode配置API, OpenCode教程, opencode.json, AI编程Agent, 终端编程助手, OpenCode providers, OpenCode国内配置, anomalyco, Claude API配置

description: OpenCode 是 2025 年增速最快的开源 AI 编程 Agent，151k+ Stars。这篇文章覆盖完整的 API 配置流程：安装、支持的 75+ 提供商、opencode.json 写法、国内用户接自定义 API 的方式，以及 Anthropic API key 被封之后的替代方案。

OpenCode 配置 API 教程：151k Stars 的终端编程 Agent，怎么接上自己的模型

OpenCode 是 anomalyco（原 SST 团队）做的开源终端编程 Agent，2025 年 4 月底发布，一年不到已经冲到 151k+ Stars，成为近两年增速最快的 AI coding agent 项目之一。

它最吸引开发者的地方不是某个单一功能，而是彻底的开放性：支持 75+ 提供商、任何 OpenAI-compatible 接口都能接进来、配置文件是纯 JSON 放在项目目录里、模型可以随时切换。如果你用过 Claude Code 但不喜欢被绑定在单一模型上，OpenCode 基本是目前最成熟的替代方案。

安装

一行命令搞定：

curl -fsSL https://opencode.ai/install | bash

macOS 也可以用 Homebrew：

brew install anomalyco/tap/opencode

装完后在项目目录运行 opencode，进入 TUI 终端界面。

自动检测 vs 手动配置

OpenCode 的 API 接入有两种路径，用哪种取决于你的使用场景。

自动检测是最省事的方式。OpenCode 启动时会扫描环境变量，按优先级顺序依次尝试：GitHub Copilot Token → ANTHROPIC_API_KEY → OPENAI_API_KEY → GEMINI_API_KEY → OPENROUTER_API_KEY……环境变量里有哪个它就用哪个。如果你的开发环境里已经设好了 API Key，直接 opencode 就能用，不用写任何配置文件。

手动配置适合需要精确控制的场景：指定默认模型、自定义 base URL、接国内中转 API、配置多个提供商按任务切换。配置文件是 opencode.json，可以放在项目根目录（只对这个项目生效）或 ~/.config/opencode/opencode.json（全局生效），项目级配置优先级更高。

一个重要的坑：Anthropic API Key 在 2026 年 1 月被封了

如果你打算用 Claude 系列模型，这个事情需要先知道：Anthropic 在 2026 年 1 月封禁了 OpenCode 通过 API Key 直连 api.anthropic.com 的访问方式。

目前还能用的方式有两种：

一是用 Claude Pro 或 Max 账号通过 OAuth 授权，在 OpenCode 里运行 /connect，选择 Anthropic，走 OAuth 流程绑定官方账号，不依赖 API Key。

二是接支持 Anthropic 协议的国内中转节点。比如七牛云 AI 推理 API（api.qnaigc.com）支持 Anthropic 原生协议，OpenCode 用自定义提供商接上去，API Key 换成七牛云的 Key，就能在国内直连跑 Claude 模型，也绕开了 Anthropic 对 OpenCode 的限制。配置如下：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "qiniu": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Qiniu AI",
      "options": {
        "baseURL": "https://api.qnaigc.com/v1",
        "apiKey": "{env:QINIU_API_KEY}"
      },
      "models": {
        "claude-sonnet-4-6": {
          "name": "Claude Sonnet 4.6"
        },
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash"
        }
      }
    }
  },
  "model": "qiniu/claude-sonnet-4-6"
}

{env:QINIU_API_KEY} 是 OpenCode 的环境变量引用语法，Key 不会硬编码进配置文件。

多模型配置和按任务分配

OpenCode 支持给不同任务分配不同模型。比如主要编码任务用 Sonnet，规划阶段用更便宜的 Haiku，这样成本和能力之间能取到一个平衡：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "qiniu/claude-sonnet-4-6",
  "small_model": "qiniu/deepseek-v4-flash",
  "agent": {
    "build": {
      "mode": "primary",
      "permission": { "edit": "allow", "bash": "allow" }
    },
    "plan": {
      "mode": "primary",
      "permission": { "edit": "deny", "bash": "deny" }
    }
  }
}

edit: allow 和 bash: allow 控制 Agent 能不能直接修改文件和执行终端命令，安全敏感的场景可以设成 ask，每次操作前会弹出确认。

常用命令

进入 TUI 之后最常用的几个：

/connect：重新配置 API Key 或 OAuth 授权
/models：切换当前会话使用的模型
/init：扫描项目结构，生成 AGENTS.md 让 Agent 理解你的代码库
opencode run "帮我写一个单元测试"：非交互模式，适合接进 CI/CD

opencode serve 可以把 OpenCode 启动成一个后台服务，暴露 API 接口，方便从其他工具调用。

接 Ollama 本地模型

如果不想用任何云端 API，接本地 Ollama 也是同样的配置逻辑：

{
  "provider": {
    "ollama": {
      "options": {
        "baseURL": "http://localhost:11434/v1"
      }
    }
  },
  "model": "ollama/qwen2.5-coder:32b"
}

本地模型没有网络延迟和 token 费用，适合代码补全这类高频低延迟场景。

OpenCode 的配置逻辑整体比较直白——环境变量放 API Key、JSON 文件写提供商配置、provider/model 格式指定模型。坑主要就是 Anthropic 那个访问限制，绕过去之后整个流程基本无障碍。官方文档在 opencode.ai/docs，providers 列表和所有配置字段都有详细说明。

七牛云 AI 推理 API Key：OpenAI + Anthropic 双协议，Claude Opus 4.7 / DeepSeek V4 / Kimi K2.6等130+全球主流模型

数据来源：OpenCode 官方文档（opencode.ai/docs，2026.04）；GitHub anomalyco/opencode（151k Stars，2026.04）

OpenCode 配置 API 教程：151k Stars 的终端编程 Agent，怎么接上自己的模型