常见问题与排障

先看自己停在哪一步。保留完整报错，会比反复重装工具更容易找到原因。

安装命令没有成功

确认打开的是教程指定的终端。Windows 的 PowerShell、命令提示符与 WSL 使用的命令可能不同，复制时不要混用。

如果刚安装完就提示“找不到命令”，先关闭终端，再重新打开，运行教程里的版本检查。仍然失败时，把完整报错和电脑系统一起提供给助手。

提示密钥错误或 401

到 XXAPI API 密钥页面 重新复制完整 Key，粘贴到工具的密钥栏，确认没有空格或残留的占位文字。

再检查请求地址。XXAPI 的 Key 需要配合 XXAPI 地址使用。旧配置仍然指向其他平台时，即使换了 Key，也不能完成接入。

提示模型不存在或没有可用渠道

报错里出现“分组 … 下模型 … 无可用渠道”，说明这枚 Key 所在的分组里没有这个模型。一枚 Key 只对应一个分组；目前 Claude 模型和 GPT 模型在不同分组，同时使用 Claude Code 和 Codex 时，请各创建一枚 Key，分别选择对应的分组。

到 模型与分组 查看完整模型 ID 和可用分组，再检查这枚 Key 的分组及模型限制。

模型显示名称与 API 模型 ID 可能不同，配置时复制完整 ID。某个分组如果限制了工具或接口，还需要按该分组的说明使用。

提示用户额度不足

报错里出现“用户额度不足”，说明账户余额不够。到 钱包 充值后，再重新发送一次。

提示 404 或返回一整页 HTML

通常先检查 API 地址。不要填注册页、控制台页面，也不要把已经由软件添加的请求路径再填一次。

工具里的地址栏	按对应教程填写
Claude Code 的 Anthropic Base URL	https://xxapi.ai
Codex 的 OpenAI 兼容 Base URL	https://xxapi.ai/v1
Cherry Studio 的提供商根地址	https://xxapi.ai
Alma 的 OpenAI 兼容 Base URL	https://xxapi.ai/v1

具体工具可能有自己的自动拼接规则，以该工具教程为准。

请求一直等待或中途断开

先记录时间和报错，确认网络能访问 XXAPI。图片请求可能需要等待更久，先不要连续点击生成。

如果总在相近时长断开，可以检查本地代理、网络工具或客户端的超时设置。已经生成的结果先查看是否能恢复，再决定要不要重新发送。

把问题交给豆包或其他 Agent

在对应教程或首页复制配置提示词，再补充下面的信息。真实密钥只在自己的电脑上填写。

我在配置 XXAPI，当前卡在下面这一步。
工具和版本：
电脑系统：
跟随的教程与步骤：
我刚执行的操作：
完整报错：

请先判断最可能的原因，只给我下一步要检查的内容。
一次处理一个问题，等我反馈后再继续。
如果你能操作本机，请先检查现有配置并保留原设置。
不要让我把完整 API Key 发进对话，也不要自行重复发送收费请求。

需要人工帮助

发邮件到 support@xxapi.ai，附上工具名称、电脑系统、卡住的步骤和完整报错。截图中遮住 API Key，保留 API 地址和模型 ID，方便定位问题。

回到工具目录