> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# OpenCode 终端使用教程

> AceDataCloud Coding Plan 集成指南 - Ace Data Cloud

[OpenCode](https://opencode.ai) 是 SST 团队推出的开源终端编程 Agent，运行在你的终端里。它可以阅读代码、修改文件、运行命令、解释错误，并协助完成日常开发任务。

OpenCode 原生支持自定义模型模型提供方，你可以通过 Ace Data Cloud 提供的 OpenAI Chat Completions 兼容代理来使用它，无需单独订阅多家模型提供方账号。配置完成后，OpenCode 会把请求发送到 `https://api.acedata.cloud/v1`，并以 `acedatacloud/<model>` 的形式选择模型（模型提供方 ID 可以自定义，本文统一使用 `acedatacloud`，与 MCP 系列文档一致）。

## 申请流程

要使用 OpenCode，首先可以到 [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)，获取您的 API Token，留作备用。

![](https://cdn.acedata.cloud/dvc3cg.jpg)

如果你尚未登录或注册，会自动跳转到登录页面邀请您来注册和登录，登录注册之后会自动返回当前页面。

在首次申请时会有免费额度赠送，可以免费体验 OpenCode 服务。

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

## 安装 OpenCode

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

### 官方脚本安装（推荐）

macOS、Linux、WSL 可以运行：

```bash theme={null}
curl -fsSL https://opencode.ai/install | bash
```

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

### Homebrew 安装（macOS / Linux）

```bash theme={null}
brew install sst/tap/opencode
```

### npm 安装

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

```bash theme={null}
npm install -g opencode-ai
```

### Windows winget 安装

```powershell theme={null}
winget install sst.opencode
```

### 检查安装

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

```bash theme={null}
opencode --version
```

实测输出例子：

```text theme={null}
1.15.13
```

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

## 配置 OpenCode

OpenCode 用 `opencode.json` 作为配置文件。根据 [OpenCode 官方配置文档](https://opencode.ai/docs/config/)，启动时按以下顺序加载，后者覆盖前者：

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

最常用的两种位置：

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

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

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

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

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

其中 `{token}` 替换为您在 Ace Data Cloud 控制台复制的 API Token。

配置后重新打开终端，或执行对应的 `source` 命令让配置立即生效：

```bash theme={null}
source ~/.zshrc
```

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

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

### 第二步：编辑全局配置

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

```bash theme={null}
mkdir -p ~/.config/opencode
touch ~/.config/opencode/opencode.json
```

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

```json theme={null}
{
  "$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 解析。

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

回到终端，运行：

```bash theme={null}
opencode models acedatacloud
```

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

```text theme={null}
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：

```bash theme={null}
cd /path/to/your/project
opencode
```

进入 TUI 后输入 `/models` 选择 `acedatacloud/claude-haiku-4-5-20251001`（或任何你喜欢的模型），就可以开始对话。

也可以用一次性命令让 OpenCode 完成单个任务：

```bash theme={null}
opencode run --model acedatacloud/MODEL_ID "Reply exactly OPENCODE_OK"
```

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

```text theme={null}
> build · claude-sonnet-4-6

Hello from AceData via OpenCode.
```

你也可以通过 [Ace Data Cloud 控制台 - 使用历史](https://platform.acedata.cloud/console/usages) 查看请求记录和扣费详情，通过 [Ace Data Cloud 控制台 - 应用列表](https://platform.acedata.cloud/console/applications) 查看剩余额度。

## 工作原理

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

工作流程如下：

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

这意味着你仍然使用原版 `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)](https://modelcontextprotocol.io)，可以在同一个 `opencode.json` 中追加 `mcp` 段，让 Agent 在写代码之余顺手生图、写歌、做视频、搜网页、压短链。AceData 提供了 11 个开箱即用的远程 MCP Server（实测共 119 个工具），详见 [OpenCode MCP 总览](https://platform.acedata.cloud/documents/opencode-mcp-all)。

> ⚠️ **重要提示（实测结论）**：当 `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` 日志。

## 了解更多

* [OpenCode 官方文档](https://opencode.ai/docs)
* [OpenCode 配置参考](https://opencode.ai/docs/config)
* [Ace Data Cloud OpenAI 服务文档](https://platform.acedata.cloud/documents/openai)
* [OpenCode + AceData 11 个 MCP 总览](https://platform.acedata.cloud/documents/opencode-mcp-all)
* [Ace Data Cloud 控制台](https://platform.acedata.cloud/console/applications)