本教程以 npm 安装的 OpenCode 1.18.23 和 yunzhi-maas-helper 0.1.x 为例，完整演示安装或更新 OpenCode、在控制台创建并复制 API Key、配置模型以及验证真实请求。Windows / Linux 操作路径完全一致。
准备 Node.js 和 npm
Helper 需要 Node.js 18 或更高版本，建议使用仍在支持期内的 LTS：
node --version npm --version
本教程实测环境为 Node.js 24.14.1 和 npm 11.11.0。
安装或更新 OpenCode
使用相同渠道安装或更新，不要混用不同的全局安装渠道：
npm install -g opencode-ai@latest
opencode --version # 本教程实测：1.18.23
创建并复制 API Key
- 登录云智 Token Hub 控制台，进入 API 密钥管理 页面，核对端点为
https://maas.piteyun.com/v1。 - 点击创建 API Key，填写名称（建议：
Coding Helper - OpenCode 教程）。 - 回到密钥列表，确认状态有效后点击目标行的复制 API 密钥。
sk-••••...•••• 是遮罩文本，不能使用。密钥泄露后请立即删除并重新创建。
安装 Helper 并粘贴密钥
# 发布后 npm install -g @yunzhi/maas-helper@latest # 当前内部阶段：从源码安装 cd yunzhi-maas-helper && npm install -g . yunzhi-helper # 不带参数进入交互菜单
在主菜单选择 输入 API Key，粘贴完整值并回车。Helper 会调用 /v1/models 实时验证密钥，确认显示 设置成功。Helper 配置保存在 ~/.yunzhi-maas-helper/config.json，不要提交到代码仓库。
选择主模型和小模型
在主菜单依次选择 配置编码工具 → OpenCode → 配置模型，Helper 会自动获取实时模型列表。推荐配置：
| OpenCode 角色 | 推荐模型 | 用途 |
|---|---|---|
| 主模型 | glm-5.3 | 日常编码、推理和复杂任务 |
| 小模型 | glm-5.3-flash | 快速、轻量的辅助任务 |
两项只是推荐默认值，也可以从实时列表中改选 qwen3.7-max、kimi-k2.7、deepseek-v4-flash-0731 等。请直接从列表中选择，不要手动填写不存在的模型 ID。提示 是否立即将配置应用到 OpenCode? (Y/n) 时直接回车接受。
配置文件位置
| 内容 | 默认位置 |
|---|---|
| Provider、端点和模型 | ~/.config/opencode/opencode.jsonc |
| 云智 API Key | ~/.local/share/opencode/auth.json |
macOS 和 Linux 上认证文件权限为 0600（Helper 已自动设置）。重写 opencode.jsonc 时原有 JSONC 注释可能丢失。
验证真实请求
- 创建空目录并启动
opencode，按 Ctrl+X 再按 M 打开模型选择器。 - 选择
yunzhi/glm-5.3，确认底部显示该模型。 - 发送：只回复"配置成功"，不要创建、修改或删除任何文件。
- 收到回复后 Ctrl+C 退出，确认测试目录仍为空后清理。
yunzhi 前缀说明 Provider 与模型目录已载入；真实回复"配置成功"则 API Key、端点和模型调用全部可用。也可以在 Helper 主菜单选择"测试真实请求"获得同样验证。
常见问题
模型选择器中没有 yunzhi
运行 yunzhi-helper，依次进入 配置编码工具 → OpenCode → 配置装载/配置刷新，完成后重启 OpenCode TUI。
API Key 无效或已过期
确认复制的是完整密钥而非遮罩文本；新建密钥后稍等片刻再重新粘贴；检查有效期与配额，必要时删除重建。
配置仍使用旧端点
正确端点为 https://maas.piteyun.com/v1。若显示其他旧地址，运行 Helper 的 配置装载/配置刷新，端点会自动规范化。