常见问题

适用对象：导入报错、消息失败或仍在使用旧服务的用户。预计耗时：5–10 分钟。

先记下错误出现在导入命令的终端，还是出现在编程助手发送消息后。两处的处理方法不同。排查时不要上传完整 Key 或含 Key 的配置文件。

导入命令报错

提示	该做什么
找不到目标工具	按对应接入页的官方链接安装工具，至少启动一次，再重新打开终端
配置码过期或已使用	回到 API 密钥列表，重新复制导入命令；配置码只能兑换一次
下载或 SHA256 校验失败	检查网络后重新生成命令；不要跳过校验或运行来源不明的导入工具
当前分组没有适用模型	检查 Key 的分组和模型目录；必要时换用支持目标工具接口的分组
检测到自定义配置变量	提示会指出变量名。确认它的用途；清除后重开终端再导入，或按对应工具的手动配置页操作。WorkBuddy 特别检查 WORKBUDDY_CONFIG_DIR、CODEBUDDY_CONFIG_DIR
本机配置语法冲突或恢复冲突	保留当前文件，按工具的手动配置页检查；不要删除 ~/.sub2api-quick-import 恢复目录

Windows 请在 PowerShell 执行复制的命令，macOS/Linux 请在终端执行。Windows 的 CMD 不能直接执行 PowerShell 版本的命令。

工具发送消息时报错

错误	先检查
401 Unauthorized	Key 是否有效、是否粘贴完整；Codex 手动配置时检查用户级 config.toml 中的凭据
403 Forbidden	Key 所在分组、账号状态与模型权限
404 Not Found	目标工具需要的接口和地址是否匹配，是否重复拼 /v1，模型 ID 是否正确
429 Too Many Requests	Key 或账号额度、速率限制及分组状态；稍后再试
model not found	该 Key 的对应目录是否列出完整 ID；Codex 要检查专用目录及 Responses 支持情况
连接超时	浏览器和终端是否都能访问主站、代理或公司网络是否拦截
配置成功但仍走旧服务	完全退出并重开工具，检查项目级配置、环境变量或另一系统用户是否覆盖用户配置

**不要看到 404 就盲目在根地址和 /v1 之间切换。**Claude Code 手动配置用 https://lianjieai.top；Codex、Pi、DeepSeek Harness 与 OpenCode 的对应模式用 https://lianjieai.top/v1；WorkBuddy 桌面版配置项要填完整 https://lianjieai.top/v1/chat/completions。见 配置速查表。

各工具额外检查

• Claude Code：ANTHROPIC_BASE_URL 不带 /v1，所选模型支持 Messages；如果系统环境已有 ANTHROPIC_API_KEY，核对它是否与配置中的 ANTHROPIC_AUTH_TOKEN 冲突。
• Codex CLI / App：只用桌面 App 时无需另装 CLI，但要先安装并打开一次 App；确认 Provider 的 wire_api = "responses"，App 和导入命令属于同一用户。手动配置时凭据保存在用户级 config.toml，不依赖临时终端环境变量。
• DeepSeek Harness：快速导入会选择 web 或 desktop profile；若工具里看不到模型，核对导入时选择的版本与当前打开的版本是否一致。自定义 profile 请按 手动配置步骤操作。
• WorkBuddy：桌面版文件是 ~/.workbuddy/models.json 顶层数组；CodeBuddy Code 的 .codebuddy 文件不能替代它。
• OpenCode：快速导入后在 /models 选择 lianjieai_quick/模型ID；手动配置后选择 lianjieai/模型ID。若已有旧版脚本配置，模型标识可能仍是 sub2api_quick/模型ID，可先用原清理命令恢复，再按新版步骤导入。
• Pi：在 /model 主动切换到 lianjieai Provider 的模型。
• CC Switch：先确认导入窗口显示正确工具、模型与 API 格式，再按应用提示启用；快速导入的清理命令不会移除 CC Switch Provider。

仍然失败

按 反馈模板记录系统、工具版本、模型 ID、发生时间及已遮挡的错误截图。只提供 Key 前后几位，绝不发送完整 Key。

完成检查

重新发送测试消息后收到正常回复；若仍失败，已按反馈模板整理了脱敏的错误信息。