OpenCode 终端使用教程

OpenCode 是 SST 团队推出的开源终端编程 Agent，运行在你的终端里。它可以阅读代码、修改文件、运行命令、解释错误，并协助完成日常开发任务。 OpenCode 原生支持自定义模型模型提供方，你可以通过 Ace Data Cloud 提供的 OpenAI Chat Completions 兼容代理来使用它，无需单独订阅多家模型提供方账号。配置完成后，OpenCode 会把请求发送到 https://api.acedata.cloud/v1，并以 acedatacloud/<model> 的形式选择模型（模型提供方 ID 可以自定义，本文统一使用 acedatacloud，与 MCP 系列文档一致）。

申请流程

要使用 OpenCode，首先可以到 Ace Data Cloud 控制台，获取您的 API Token，留作备用。

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。在首次申请时会有免费额度赠送，可以免费体验 OpenCode 服务。

一份 Token 同时可以用于 OpenCode 接入 AceData 的 11 个 MCP 服务，统一计费。Token 仅保存在你本机配置或环境变量里，不要提交到公开仓库。

安装 OpenCode

OpenCode 支持 macOS、Linux、Windows 和 WSL。可以用官方一键脚本，也可以用 Homebrew 或 npm 安装。

官方脚本安装（推荐）

macOS、Linux、WSL 可以运行：

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

Windows 用户可在 WSL 或 Git Bash 中运行上面的安装脚本，或使用下文的 winget / scoop 包管理器安装。

Homebrew 安装（macOS / Linux）

brew install sst/tap/opencode

npm 安装

如果你已经安装了 Node.js 18+，可以通过 npm 安装：

npm install -g opencode-ai

Windows winget 安装

winget install sst.opencode

检查安装

安装完成后，重新打开终端，然后检查命令是否可用：

opencode --version

实测输出例子：

1.15.13

如果提示 command not found，通常是当前终端还没有加载新的 PATH，请关闭并重新打开终端。macOS Homebrew 安装路径是 /opt/homebrew/bin/opencode，可用 which opencode 查看。

配置 OpenCode

OpenCode 用 opencode.json 作为配置文件。根据 OpenCode 官方配置文档，启动时按以下顺序加载，后者覆盖前者：

全局配置：~/.config/opencode/opencode.json（也支持 opencode.jsonc 同目录变体写带注释配置）
OPENCODE_CONFIG 环境变量：指向任意自定义配置文件路径
项目配置：项目根目录下的 opencode.json（向上查找到 Git root 为止）

最常用的两种位置：

全局配置：~/.config/opencode/opencode.json，对所有项目生效。
项目级配置：项目根目录下的 opencode.json，仅对当前项目生效，会覆盖全局。

下面以全局配置示范，把 AceData 注册成一个名为 acedatacloud 的自定义模型提供方。

第一步：导出 API Token 到环境变量

推荐把 API Token 写入 Shell 配置文件，例如 ~/.zshrc、~/.bashrc 或 ~/.bash_profile：

export ACEDATACLOUD_API_KEY="{token}"

其中 {token} 替换为您在 Ace Data Cloud 控制台复制的 API Token。配置后重新打开终端，或执行对应的 source 命令让配置立即生效：

source ~/.zshrc

⚠️ 如果你把 Token 放在的是单独的 .env 文件里，而且文件中是 ACEDATACLOUD_API_KEY=...（没有 export 前缀），那么普通 source .env 只会设置 shell 变量不会导出到子进程，OpenCode 启动时读不到。请改用：
set -a && source .env && set +a
生效后 opencode debug config 里看到 "Authorization": "Bearer <你的Token>" 才算成功；如果看到 "Bearer "（后面是空）说明占位符没被解析。

OpenCode 配置文件里使用 {env:ACEDATACLOUD_API_KEY} 占位符引用这个环境变量，避免把真实 Token 直接写入文件。

第二步：编辑全局配置

如果该文件不存在，可以新建它：

mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json

把以下内容写入 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "acedatacloud": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ace Data Cloud",
      "options": {
        "baseURL": "https://api.acedata.cloud/v1",
        "apiKey": "{env:ACEDATACLOUD_API_KEY}"
      },
      "models": {
        "MODEL_ID": { "name": "MODEL_ID" }
      }
    }
  }
}

各字段说明：

字段	说明
`provider.acedatacloud`	模型提供方在 OpenCode 中的内部 ID，可自定义（本文与 MCP 系列文档一致使用 `acedatacloud`）
`npm`	使用的 AI SDK 包，OpenAI 兼容接口固定为 `@ai-sdk/openai-compatible`
`name`	在 TUI `/models` 选择器中显示的名字
`options.baseURL`	Ace Data Cloud 的 OpenAI Chat Completions 代理地址
`options.apiKey`	API Token，建议使用 `{env:...}` 占位符
`models`	当前模型提供方下要暴露给 OpenCode 的模型列表，key 是模型 ID

models 里只列你需要的模型即可，后续想增删模型时编辑这一段就行，不需要重启系统。

💡 也可以使用 opencode.jsonc 后缀写带注释的配置，文件位置与 opencode.json 相同，OpenCode 会按 JSONC 解析。

第三步：验证模型提供方已经注册

回到终端，运行：

opencode models acedatacloud

可以看到所有注册的模型，以上面示例配置为例实测输出：

acedatacloud/claude-haiku-4-5-20251001
acedatacloud/claude-opus-4-7
acedatacloud/claude-sonnet-4-6
acedatacloud/deepseek-v3.2-exp
acedatacloud/gemini-2.5-pro
acedatacloud/gpt-5
acedatacloud/gpt-5-mini

如果没有看到 acedatacloud/...，说明配置文件没有被读取。可以加 --print-logs --log-level INFO 再跑一次，确认 service=config path=... loading 是否扫到了你的配置文件。

第四步：发起第一个会话

进入你的项目目录，然后直接启动 TUI：

cd /path/to/your/project
opencode

进入 TUI 后输入 /models 选择 acedatacloud/claude-haiku-4-5-20251001（或任何你喜欢的模型），就可以开始对话。也可以用一次性命令让 OpenCode 完成单个任务：

opencode run --model acedatacloud/MODEL_ID "Reply exactly OPENCODE_OK"

下面是一次实测的输出，证明配置生效：

> build · claude-sonnet-4-6

Hello from AceData via OpenCode.

你也可以通过 Ace Data Cloud 控制台 - 使用历史查看请求记录和扣费详情，通过 Ace Data Cloud 控制台 - 应用列表查看剩余额度。

工作原理

OpenCode 通过 Vercel AI SDK 的 @ai-sdk/openai-compatible 适配器请求兼容 OpenAI Chat Completions 协议的服务。Ace Data Cloud 在 https://api.acedata.cloud/v1/chat/completions 提供该兼容代理，因此 OpenCode 不需要本地代理程序，也不需要任何插件。工作流程如下：

OpenCode 启动时按官方文档顺序读取 ~/.config/opencode/opencode.json（全局）→ $OPENCODE_CONFIG（自定义路径）→ 项目根目录下的 opencode.json，后者字段覆盖前者。
当请求 acedatacloud/<model> 时，OpenCode 加载 provider.acedatacloud 配置块，解析 options.apiKey 中的 {env:ACEDATACLOUD_API_KEY} 占位符。
请求被构造成 OpenAI Chat Completions 格式，加上 Authorization: Bearer <token>，POST 到 https://api.acedata.cloud/v1/chat/completions。
Ace Data Cloud 校验 Token、检查额度，转发到对应模型的目标模型服务，并将响应（流式或非流式）按原协议透传回 OpenCode。
请求完成后，平台根据实际使用量记录用量并扣减额度。

这意味着你仍然使用原版 opencode 命令和 TUI 体验，只是把底层模型服务切换为 Ace Data Cloud。

配置模型

MODEL_ID 必须来自 Coding 选择器中 opencode-cli-provider 的当前 allowlist。不要把本文历史实测模型或 /v1/models 的全部返回值直接当成 OpenCode tool-loop 已验证清单。可在 TUI 中使用 /models 切换已写入 provider.acedatacloud.models 的 exact model。

与 MCP 工具一起用

OpenCode 同样支持 Model Context Protocol (MCP)，可以在同一个 opencode.json 中追加 mcp 段，让 Agent 在写代码之余顺手生图、写歌、做视频、搜网页、压短链。AceData 提供了 11 个开箱即用的远程 MCP Server（实测共 119 个工具），详见 OpenCode MCP 总览。

⚠️ 重要提示（实测结论）：当 opencode.json 中同时配置了大量 MCP 工具时，建议优先选择 OpenAI 系列模型（如 gpt-5、gpt-5-mini）作为对话模型。Claude 系列模型对 MCP 工具 JSON Schema 的校验更严格，在工具数量较多时容易在服务返回 Improperly formed request（实测：acedatacloud/claude-haiku-4-5-20251001、acedatacloud/claude-sonnet-4-6 在挂载全部 11 个 MCP 时均报这个错）。只做对话、不调用 MCP 工具时，Claude 系列模型可以正常使用（本文上面的 Hello from AceData via OpenCode. 实测即用 claude-sonnet-4-6）。

故障排查

Model not found: acedatacloud/...：模型 ID 拼写错了，或没在 provider.acedatacloud.models 里登记。打开 ~/.config/opencode/opencode.json 检查 key。
401 Unauthorized / 鉴权失败：通常是 ACEDATACLOUD_API_KEY 未导出到当前终端。执行 echo $ACEDATACLOUD_API_KEY 看看是否有值，没有就重新 source ~/.zshrc。如果是 .env 文件没有 export 前缀，请用 set -a && source .env && set +a。
Improperly formed request：目标服务模型拒绝了请求。如果当前会话挂载了 MCP 工具且选择的是 Claude 模型，可切换到 acedatacloud/gpt-5-mini 重试；或者临时禁用相关 MCP（把 enabled 改为 false）再发请求。
opencode mcp list 报 401 / SSE error: Non-200 status code (401)：检查 MCP 配置是否加了 "oauth": false。AceData MCP 走 Bearer Token 鉴权，不走 OAuth，必须显式关闭 OAuth 才能调用成功。
配置文件改了不生效：OpenCode 启动时一次性读取配置，修改后请退出 TUI 重新启动 opencode。如需调试，可加 --print-logs --log-level INFO 查看配置加载路径和顶部会看到的 service=config path=... loading 日志。

入门

核心概念

AI 聊天

AI 图像

AI 视频

AI 音频

网络与数据

验证码

身份验证

代理

高级

Coding

OpenCode 终端使用教程

申请流程

安装 OpenCode

官方脚本安装（推荐）

Homebrew 安装（macOS / Linux）

npm 安装

Windows winget 安装

检查安装

配置 OpenCode

第一步：导出 API Token 到环境变量

第二步：编辑全局配置

第三步：验证模型提供方已经注册

第四步：发起第一个会话

工作原理

配置模型

与 MCP 工具一起用

故障排查

了解更多

​申请流程

​安装 OpenCode

​官方脚本安装（推荐）

​Homebrew 安装（macOS / Linux）

​npm 安装

​Windows winget 安装

​检查安装

​配置 OpenCode

​第一步：导出 API Token 到环境变量

​第二步：编辑全局配置

​第三步：验证模型提供方已经注册

​第四步：发起第一个会话

​工作原理

​配置模型

​与 MCP 工具一起用

​故障排查

​了解更多

申请流程

安装 OpenCode

官方脚本安装（推荐）

Homebrew 安装（macOS / Linux）

npm 安装

Windows winget 安装

检查安装

配置 OpenCode

第一步：导出 API Token 到环境变量

第二步：编辑全局配置

第三步：验证模型提供方已经注册

第四步：发起第一个会话

工作原理

配置模型

与 MCP 工具一起用

故障排查

了解更多