OpenCode 安装与配置教程（2026 最新 V2）：安装、免费模型、接第三方 API

先注意一件事：2026 年 10 月 OpenCode 2 已经发布，npm 包名从 opencode-ai 换成了 @opencode/cli，配置写法也有变化。网上几乎所有教程讲的都还是旧版，照着装会装成 1.x。本文按 V2 写，用到 V1 的地方会单独标出。所有命令都在 2026 年 10 月 15 日实测过。

OpenCode 1 和 2：先弄清你要装哪个

两个版本都叫 opencode 命令，不能同时装。已经装了 V1 的，先卸载再装 V2：

npm uninstall -g opencode-ai

否则 PATH 里排在前面的旧版会被优先运行。我们实测，V2 安装脚本检测到本机已有 V1 时，会显示 Installed version: 1.19.0.，但并不会帮你卸载。

OpenCode 是什么

OpenCode 是一个开源（MIT 协议）的 AI 编程助手，和 Claude Code、Codex 是同一类工具：在终端里读代码、改文件、跑命令。它最大的不同是不绑定任何一家模型：

• 内置了几十家模型服务商的目录，Anthropic、OpenAI、Google、DeepSeek、Kimi 等都能直接连。
• 可以接任何 OpenAI 兼容或 Claude 兼容的第三方服务。
• 自带一批限时免费的模型，装好不用任何账号就能先试。

它有两个内置工作模式，按 Tab 键切换：build（默认，可以改文件、跑命令）和 plan（只读，适合先分析、出方案）。

安装

方法一：一键安装（Mac / Linux）

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

我们实测 8 秒装完，程序装在 ~/.opencode/bin。V2 的安装脚本从 npm 官方源下载程序，不经过 GitHub。

安装脚本会把 ~/.opencode/bin 加进你的 shell 配置文件。如果你的电脑上还没有 ~/.zshrc（新 Mac 常见），它会提示：

No config file found for zsh. You may need to manually add to PATH:
  export PATH=/Users/你的用户名/.opencode/bin:$PATH

照着手动加一下：

echo 'export PATH="$HOME/.opencode/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

方法二：npm（国内网络推荐，Windows 也用这个）

需要先装好 Node.js（建议 22 版）。

npm install -g @opencode/cli --registry=https://registry.npmmirror.com

我们实测 27 秒装完，程序本体比较大，安装后约占 190 MB：

added 2 packages in 27s

V2 官方说明 Windows 上的包管理器（Scoop、Chocolatey 等）暂不支持，Windows 用户用 npm，或者在官网下载对应的程序文件。

方法三：Homebrew（Mac / Linux）

brew install anomalyco/tap/opencode-v2

装完检查

打开一个新终端窗口：

opencode --version

opencode v2.0.29

进入项目文件夹，运行 opencode 打开全屏界面；opencode run "问题" 不进界面，回答完就退出，适合脚本。

用自带的免费模型

不用注册、不用密钥，装好就能用。查看当前有哪些免费模型：

opencode models

我们 10 月 15 日在全新环境里看到的是这些（名单经常变，以你看到的为准）：

opencode/big-pickle
opencode/exo-free
opencode/ling-3.0-flash-fin-free
opencode/ling-3.1-flash-free
opencode/longcat-2.5-preview-free
opencode/mimo-v2.6-flash-free
opencode/muse-spark-1.3-contributor-free
opencode/nemotron-3-ultra-free
opencode/nemotron-3.5-lightning-free
opencode/space-bunny-free
opencode/step-5-preview-free

在界面里输入 /models 选一个就能开始。几点提醒：

• 大多是「限时免费」，随时可能下线。我们实测，2.0.29 全新安装后不选模型直接用，会默认用 exo-free，然后报 Model exo-free has been deprecated.（这个模型已下线），手动换一个就好。
• 名字带 contributor 的模型，会把你的对话拿去训练模型，这是 OpenCode 官方文档写明的。别在这类模型里放公司代码和隐私内容。
• 部分免费模型有地区限制，官方文档里个别模型写明不对中国大陆、香港、澳门提供。
• 免费模型适合尝鲜。正式干活建议接你自己的模型服务。

连接模型服务商

官方支持的服务商（Anthropic、OpenAI、DeepSeek、Kimi 等）：在界面里输入 /connect，选服务商，粘贴 API Key，再用 /models 选模型。

列表里没有的第三方服务，写配置文件，见下一节。

接第三方 API（V2 写法）

配置文件在 ~/.config/opencode/opencode.jsonc（只对某个项目生效的话，放在项目根目录的 opencode.jsonc），没有就新建。以 api.foo 为例，同时接 GPT 和 Claude 两类模型：

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "apifoo": {
      "name": "api.foo",
      "env": ["APIFOO_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": { "baseURL": "https://api.foo/v1" },
      "models": {
        "gpt-6.1-sol": { "name": "GPT-6.1 Sol" }
      }
    },
    "apifoo-claude": {
      "name": "api.foo (Claude)",
      "env": ["APIFOO_API_KEY"],
      "package": "@opencode/ai/providers/anthropic-compatible",
      "settings": { "baseURL": "https://api.foo/v1" },
      "models": {
        "claude-sonnet-5-5": { "name": "Claude Sonnet 5.5" }
      }
    }
  },
  "model": "apifoo-claude/claude-sonnet-5-5"
}

然后把密钥设成环境变量（Mac 写进 ~/.zshrc，Windows 用 setx APIFOO_API_KEY "sk-你的密钥" 后重开终端）：

echo 'export APIFOO_API_KEY="sk-你的密钥"' >> ~/.zshrc && source ~/.zshrc

每一项是什么意思：

我们怎么验证的：用一把故意写错的密钥，分别测了两种格式。OpenCode 都把请求发到了 api.foo，api.foo 的服务器日志里分别收到了 /v1/chat/completions 和 /v1/messages 请求，并返回了「无效的令牌」：

> build · claude-sonnet-5-5
Error: 无效的令牌 (request id: …)

报错来自服务商、说明配置已经生效，换上正确的密钥就能用。用 Claude 模型时建议走 anthropic-compatible，用的是 Claude 原生接口。

改完配置不生效时，运行 opencode reload 让后台服务重新加载配置。

还在用 V1 的写法

如果你暂时还用 OpenCode 1（opencode-ai），自定义服务商这样写，我们在 1.19.0 上实测可以连到 api.foo：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "apifoo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "api.foo",
      "options": {
        "baseURL": "https://api.foo/v1",
        "apiKey": "{env:APIFOO_API_KEY}"
      },
      "models": {
        "gpt-6.1-sol": { "name": "GPT-6.1 Sol" }
      }
    }
  },
  "model": "apifoo/gpt-6.1-sol"
}

上手：常用操作

给项目写说明：在项目根目录放一个 AGENTS.md，写上怎么运行、代码规范等，OpenCode 每次都会读。注意 V2 只认 AGENTS.md，不会读 CLAUDE.md，从 Claude Code 转过来的项目要改个名或复制一份。

常见报错与解决办法

1. Failed to fetch version information

运行旧的 V1 安装脚本（https://opencode.ai/install）时出现。这个脚本要先访问 GitHub 的接口查最新版本，国内网络连不上 GitHub，或者你用的代理出口被 GitHub 限流了（我们实测遇到的就是限流），都会这样。改用 V2 安装脚本（它从 npm 下载），或者用 npm 国内镜像安装。

2. Model exo-free has been deprecated.

V2 全新安装后没选模型就开始用，默认用到了一个已经下线的免费模型。在界面里用 /models 换一个，或者在配置文件里写上 model。

3. Model unavailable: 服务商/模型名

OpenCode 找不到这个模型：

• 模型名和配置里 models 下的键名不一致，或者服务商 ID 写错了；
• 在 V2 里用了 V1 的写法（见上文的警告）。

4. Database is not empty and has no session table

用过 V2 之后又换回 V1 时会出现。V2 已经把本地数据库改成了新格式，V1 读不了。我们实测复现过。要么继续用 V2，要么退回 V1 前先备份并清掉 OpenCode 的数据目录（opencode debug paths data 可以查看位置）。

5. 无效的令牌、401

请求到了服务商，但密钥不对。检查环境变量 APIFOO_API_KEY 是否设置成功（新开一个终端运行 echo $APIFOO_API_KEY），密钥有没有复制完整。

6. 装了 V2，运行的还是 V1

opencode --version 显示 1.x，说明 PATH 里旧版排在前面。先 npm uninstall -g opencode-ai 卸掉旧版，再重开终端。

卸载

V2 自带卸载命令，先预览会删什么，再确认：

opencode uninstall --dry-run
opencode uninstall

它会删除程序和缓存，不会删除你的会话记录、配置和状态。npm 安装的也可以直接：

npm uninstall -g @opencode/cli

相关阅读

• Claude Code 安装教程：Mac、Windows、Linux 三种装法与国内常见问题
• Codex 安装与使用教程：一键安装、npm 国内镜像、config.toml 接第三方 API
• Gemini CLI 安装与使用教程