常见问题 FAQ

401 / Invalid API Key

Key 复制不完整或有空格
Key 被禁用 / 删除
客户端填错字段

处理：重新复制、确认启用，或新建 Key。

403 / 无权访问某分组

创建 Key 时未选择该分组
账号没有该分组权限

处理：编辑/重建 Key 并勾选对应分组；若下拉没有该分组，联系服务商开通。

余额不足 / quota

账户余额为 0
单 Key 配额耗尽
4K 生图消耗更高

处理：充值或调高 Key 配额。

模型不存在 / 无可用渠道

模型名写错
分组没有对应渠道
模型临时下线

处理：从定价页原样复制模型名；换同分组可用模型。

超时 / 无响应

网络、代理干扰
Base URL 路径错误
生图 / 4K 请求过久被断开

处理：浏览器先打开服务商网站；用验证页 curl 排除客户端问题；生图先降到 1K。

AI Toolbox / CC Switch 已启用但 CLI 仍旧配置

未新开终端
多个工具同时改配置文件（AI Toolbox、CC Switch、Codex++）
在 AI Toolbox 里只保存了供应商，还没有点应用

处理：只保留一个配置入口；确认卡片为 已应用；重启终端。

Windows 上找不到 `~/.claude` / `~/.codex` 这类路径

文档里的 ~/... 是用户主目录简写，不是项目目录。Windows 请换成 %USERPROFILE%\...（例如 %USERPROFILE%\.claude\settings.json），在资源管理器地址栏粘贴即可。完整约定见这是什么 → 配置文件路径约定。

Cherry 绘画没有模型 / 助手选不到 gpt-image

gpt-image-*：端点类型改为 图像生成（OpenAI），到启动台绘画页选用；助手列表选不到是正常的。
要 4K：不要用 gpt-image，改用 Gemini 生图 + 助手自定义参数。

详见生图教程。

调不出 4K

绘画页（含 gpt-image）通常没有真正的 4K。请用 Gemini 生图模型 + 助手参数 imageConfig.imageSize = "4K"。见生图教程。

quality=high 但不够清晰

质量与分辨率不是一回事。gpt-image 请改尺寸枚举；Gemini 请提高 imageSize（1K/2K/4K）。

OpenClaw / Hermes 命令找不到

未安装 Node.js / npm，或版本过低：见安装 Node.js 与 npm
全局 npm bin 未进 PATH
Node 版本不满足
安装包名有变，以官网为准