高级配置与故障恢复

推荐：下载后双击，不用终端#

在 API 密钥 → 客户端中选择密钥，点击“下载完整配置包”。只下载一个 ZIP，配置已经放在包内。Windows 右键 ZIP → 全部提取，打开文件夹后双击auto-install.cmd；Mac 双击 ZIP 后打开 auto-install.command。首次自动准备 Node.js，不用再选择配置文件。

下载前默认勾选将所选密钥更新为套餐内全部可用模型。若只想保留自己原来的模型选择，可以取消勾选。页面会显示这次可同步的数量；已暂停或下架的线路不会加入。安装时会重新读取最新模型目录，因此数量可能随着线路状态变化。

Windows 拦截脚本时#

智能应用控制可能阻止未受信任的 CMD 脚本，ZIP 内脚本也可能被拦截。不要关闭安全保护。模型恢复可以在页面选择 models.json，仅在浏览器内修复并下载，然后备份并替换原文件；安装需联系管理员获取受信任程序。

高级用户：Skill 和终端方式#

Adapter 面向 CodeBuddy / WorkBuddy 等本地客户端。它把客户端协议、模型目录和平台个人密钥连接起来。Codex CLI 与 Claude Code 可按前两节直连，无需强制安装本地 Adapter。

安装步骤#

1. 先在平台创建有效密钥，再打开 API 密钥 → 客户端。
2. 选择密钥，下载完整配置 ZIP。CodeBuddy 和 WorkBuddy 共用一个下载入口，工具会分别配置已使用过的客户端。请在 24 小时内安装，不要转发配置包。
3. 按页面提示在目标客户端安装技能，使用 setup 文件绝对路径运行安装器。Windows 路径有空格时必须加引号。
4. 安装器兑换授权并写入客户端模型配置。新版连接云端 Adapter，不需要设置本地代理或登录启动项。
5. 选择 pt/ 前缀的模型，发送一条简单消息，再验证工具调用。

授权和本地运行#

新下载的配置包有效期为 24 小时，同一电脑、同一用户可重复安装或同步，源密钥须保持有效。过期后删除旧 ZIP 和解压文件夹，回到 API 密钥页面重新下载。已使用或旧版已过期时重新从平台下载；短时安装重试需要沿用同一安装凭证，不能复制到另一台机器。客户端凭证继承源密钥权限，源密钥停用、到期或账户暂停会影响本地调用。

新版一键配置默认连接平台托管 Adapter，不需要本地代理一直运行。旧版使用 localhost 地址的配置才需要本地进程。配置完成后，请发送一条消息验证；模型列表出现不代表调用成功。

出现 401 或“无效的 API Key”#

这表示客户端保存的凭证不存在、已停用、已过期，或关联的主 API Key 已被停用、删除。反复重试和“模型不见了 / 恢复”工具都不会重新签发凭证。请完全退出 CodeBuddy / WorkBuddy，在平台 API 密钥页选择一把有效的主密钥，重新下载完整配置包，运行 install 安装文件后再打开客户端并新建对话。更换配置前不要删除原 models.json，安装器会备份并保留其他供应商模型。

模型不见了？不用 AI 也能恢复#

先完全退出客户端，在 API 密钥页点击“模型不见了 / 恢复”，下载并解压独立恢复包。双击对应客户端的 find-models 文件，Windows 选 .cmd，macOS 选 .command。需要 Node.js 20+，但不需要 AI、登录或密钥。工具先备份，再解除只显示平台模型的限制，不删除模型。

命令在恢复包解压目录中执行，不能发给 AI。WorkBuddy 请把 codebuddy 改为 workbuddy；只在某个项目出问题时，加 --cwd 并填写项目完整路径。rollback 文件用于完整回退，会撤销安装后的配置修改，运行前会再次确认。没有备份时不能凭空还原。

不方便运行命令时：先退出客户端，在用户或项目的 .codebuddy / .workbuddy 目录，把 models.json 改名为 models.json.disabled，再打开客户端。这会暂时停用该文件里的全部自定义模型；不要删除文件，需要时可改回原名。

升级与排障#

1. 升级使用平台最新完整包，避免混用旧安装器和新运行时。
2. 授权失败：重新生成 setup 文件；检查系统时间和网络。
3. 模型存在但 502：检查代理健康、本地日志及平台请求记录，再核对模型协议。
4. 源密钥更换：重新生成对应配置，不能仅改模型名称。
5. 分享日志前移除密钥、setup 授权和个人信息。