使用 X-AIO Coding Helper 配置 OpenCode

本教程以 macOS、npm 安装的 OpenCode 1.18.23 和 X-AIO Coding Helper 当前 0.9.x 主线为例，完整演示安装或更新 OpenCode、创建并从列表复制 API Key、配置模型以及验证真实请求的过程。教程兼容 0.7.x 或更高版本，安装使用 @latest 获取当前主线的最新补丁。

1. 准备 Node.js 和 npm

Coding Helper 需要 Node.js 18 或更高版本。使用 npm 安装 OpenCode 时，建议使用仍在支持期内的 Node.js LTS，并先检查环境：

node --version
npm --version

如果尚未安装 Node.js，请从 Node.js 官网 安装当前 LTS 版本。本教程实测环境为 Node.js 24.14.1 和 npm 11.11.0。

2. 安装或更新 OpenCode

本机原来通过 npm 安装 OpenCode，因此使用相同渠道更新：

npm install -g opencode-ai@latest
opencode --version

本教程更新后显示 1.18.23。已经安装 OpenCode 时，也可以使用官方升级命令：

opencode upgrade --method npm

如果你使用 Homebrew、安装脚本或桌面应用，请遵循 OpenCode 官方安装文档 中对应渠道的更新方式，不要混用不同的全局安装渠道。

3. 创建并从列表复制 X-AIO API Key

1. 打开 X-AIO API 密钥管理 并登录演示账号。
2. 核对页面中的 OpenAI 生态端点为 https://llm-api.x-aio.com/v1。
3. 点击 创建新密钥。
4. 在“密钥用途”中填写 Coding Helper - OpenCode 教程。
5. 选择 90天，确认页面给出的到期时间，然后点击 创建密钥。
6. 创建成功提示只说明“新密钥已添加到列表”，不会展示或返回一枚额外的明文密钥。点击 OK 返回密钥列表。
7. 在列表中找到 Coding Helper - OpenCode 教程，确认状态为“有效”，再点击该行的 复制 API 密钥。

新密钥并不是只在创建时显示一次。回到列表后，可以通过目标行的 显示 API 密钥 查看完整值，也可以点击 复制 API 密钥 直接写入剪贴板；本教程使用后者。列表默认只显示类似 sk-••••...•••• 的遮罩值，不要复制肉眼可见的遮罩文本。

4. 安装 Coding Helper 并粘贴 API Key

使用 @latest 安装 Coding Helper 当前 0.9.x 主线。教程最低要求为 0.7.x 或更高版本，不锁定某个精确 patch：

npm install -g @x-all-in-one/coding-helper@latest
xaio-chelper

安装完成后只需要运行不带参数的 xaio-chelper，后面的密钥和工具配置都在交互菜单中完成。首次运行时，按顺序操作：

1. 在语言选择界面中选择 [CN] 中文，按回车确认。
2. 向导会自动进入 API Key 页面；选择 输入 API Key，无需先返回主菜单。
3. 看到 请在这里输入您的 API key, 回车键确认: 后，粘贴刚才从密钥列表复制的完整值，再按回车。
4. 等待 Helper 调用 https://llm-api.x-aio.com/v1/models 验证密钥，确认显示 设置成功。
5. 回到主菜单，确认 API Key 状态显示为 已设置。

如果不是首次运行，裸命令会直接打开主菜单。此时依次选择 配置 API Key → 更新 API Key；只有尚未保存密钥时，该选项才显示为 输入 API Key。后续所有 Coding Helper 操作也都从这个交互菜单继续。

Helper 自身的配置保存在 ~/.xaio-chelper/config.yaml。不要把这个文件提交到代码仓库。

5. 选择主模型和小模型

继续使用刚才打开的 Coding Helper 交互向导。在主菜单中按顺序操作：

1. 选择 配置编码工具。
2. 在工具列表中选择 OpenCode。
3. 在 OpenCode 管理菜单中选择 配置模型 - (选择主模型/小模型)。
4. 在“选择主模型”中选择 deepseek-v4-pro-0813。
5. 在“选择小模型 (快速/轻量)”中选择 deepseek-v4-flash-0731。
6. 提示 是否立即将配置应用到 OpenCode？ (Y/n) 时直接按回车接受 Yes。

如果已经退出 Coding Helper，请重新运行裸命令 xaio-chelper，再从主菜单进入同一路径；不要使用快捷子命令跳过菜单。

选择 Yes 后会立即同步，无需再手动执行“配置刷新”。返回管理菜单后应看到：

• X-AIO Helper 与 OpenCode 的 API Key 遮罩前缀一致。
• 端点为 https://llm-api.x-aio.com/v1。
• 主模型和小模型与刚才的选择一致。
• 状态为 配置已同步。

“刷新模型列表”会更新 OpenCode 中可选的 X-AIO 模型目录，并规范化 X-AIO Provider 元数据和端点，但不会替你改变当前主模型或小模型。只有之前选择了 No、配置被其他工具改动或状态不一致时，才需要在该菜单中选择“配置装载/配置刷新”。

Helper 会把公开配置和凭据分开保存：

macOS 和 Linux 上，认证文件权限应为 0600。旧版 opencode.json 会迁移为 opencode.jsonc，旧的 provider.xaio.options.apiKey 会从公开配置中移除并写入认证文件。其他可解析的 Provider 和配置字段会保留，但 JSONC 注释可能在重写时丢失。

6. 在空目录中使用 OpenCode TUI 验证真实请求

创建一个新的空目录，避免测试请求接触重要项目：

demo_dir="$(mktemp -d /tmp/xaio-opencode-demo.XXXXXX)"
original_dir="$PWD"
printf '%s\n' "$demo_dir"
if [ -n "$(ls -A "$demo_dir")" ]; then
  ls -la "$demo_dir"
else
  printf '%s\n' '(empty)'
fi
cd "$demo_dir"
opencode

OpenCode TUI 打开后，按界面完成验证：

1. 先按 Ctrl+X，松开后再按 M，打开模型选择器。这是 OpenCode 1.18.23 的默认按键；如果你修改过快捷键，请使用界面中显示的模型选择操作。
2. 在选择器中搜索并选择 xaio/deepseek-v4-pro-0813，按回车确认。也可以选择你在第 5 节实际配置的其他模型。
3. 确认 TUI 底部显示刚选中的模型，然后在输入框发送：只回复“配置成功”，不要创建、修改或删除任何文件。
4. 等待真实请求完成，并确认回复为 配置成功。能在选择器中看到 xaio 模型说明 Provider 和模型目录已经载入；真实回复成功则进一步验证 API Key、端点和模型调用均可用。
5. 界面空闲后按 Ctrl+C 退出 OpenCode。也可以先按 Ctrl+X，松开后再按 Q。

OpenCode 会在自己的用户数据目录保存本地会话，但这次测试不应在临时项目目录中创建文件。回到终端后检查目录：

if [ -n "$(ls -A .)" ]; then
  ls -la .
else
  printf '%s\n' '(empty)'
fi

如果输出为 (empty)，表示测试目录保持为空；如果列出了文件，先检查内容和来源，不要直接删除。确认目录仍为空后返回原目录并移除它：

cd "$original_dir"
rmdir "$demo_dir"

7. 常见问题

OpenCode 模型选择器中没有 xaio

运行裸命令 xaio-chelper，依次进入 配置编码工具 → OpenCode → 配置装载/配置刷新。完成后重新启动 OpenCode TUI，再打开模型选择器核对。

模型列表缺少新模型

运行裸命令 xaio-chelper，依次进入 配置编码工具 → OpenCode → 刷新模型列表 - (更新可用模型到配置)。刷新不会改变当前主模型和小模型；完成后重新启动 OpenCode TUI 并打开模型选择器。如需更换默认模型，请回到 OpenCode 管理菜单选择 配置模型。

API Key 无效或已过期

• 确认点击的是目标密钥行的 复制 API 密钥，而不是复制页面上的遮罩文本。
• 新建密钥后等待片刻，再运行裸命令 xaio-chelper，选择 配置 API Key → 更新 API Key 重新粘贴。
• 检查密钥有效期和工作空间；必要时删除旧密钥并创建新的有限期密钥。

配置仍使用旧端点

X-AIO Provider 的 baseURL 应为：

https://llm-api.x-aio.com/v1

如果仍显示 https://code-api.x-aio.com/v1 或其他旧地址，请运行裸命令 xaio-chelper，依次进入 配置编码工具 → OpenCode → 配置刷新。

8. 官方参考

• OpenCode 安装与入门
• OpenCode 配置文件
• OpenCode Providers
• OpenCode 模型
• OpenCode CLI
• OpenCode 权限