常见问题排查
使用 KIE skill 时的常见问题和解决办法。
安装与 API Key
| 现象 | 原因 / 解决 |
|---|---|
npx: command not found | 没有安装 Node.js。装好后重新运行 npx skills add https://kie.ai。 |
| Agent 好像没用上 skill | 安装后重启 Agent。也可以在请求里直接点名：“Use the kie-models skill to …”。 |
Agent 提示缺少 KIE_API_KEY | 启动 Agent 的 shell 里没有这个变量。导出后，从同一个 shell 重启 Agent。 |
401 Unauthorized | Key 错误或已失效，或者放错了请求头。KIE 只认 Authorization: Bearer <key>，名为 apikey 的请求头会被拒绝。到 kie.ai/api-key 核对。 |
| Windows 下变量仍然不生效 | setx 只对之后新开的窗口生效。关掉所有终端（包括 VS Code、Cursor 等编辑器内置终端）后重开，或在当前窗口设 $env:KIE_API_KEY。 |
PowerShell 的 curl 报参数错误 | PowerShell 里 curl 是 Invoke-WebRequest 的别名，改用 curl.exe。 |
jq: command not found | 安装 jq：brew install jq、apt install jq 或 winget install jqlang.jq。 |
运行模型（kie-models）
| 现象 | 原因 / 解决 |
|---|---|
| Agent 选的模型不是你想要的 | 在请求里点名模型，例如“用 GPT Image 2”。 |
| 任务失败 | 到 kie.ai/logs 查看任务和错误信息，再让 Agent 调整参数重试。 |
| 积分不足 | 到 kie.ai/pricing 充值后，让 Agent 重新运行任务。 |
| 结果链接打不开了 | 生成的文件保留 14 天。让 Agent 把结果保存到本地路径，就能留一份副本。 |
编程 Agent（kie-chat-agents）
| 现象 | 原因 / 解 决 |
|---|---|
| 接入 Agent 后请求报错或结果异常 | 所用模型可能是仅支持对话调用的较早版本（模型页标有「仅支持对话调用」）。换成该系列的最新版模型。 |
model not found | 模型名不在该 Agent 的 listing 里。从对应接口（/anthropic/v1/models、/openai/v1/models 或 /xai/v1/models）列出模型，填里面的 id。 |
请求路径重复，例如 /v1/v1/messages 或 /responses/responses | base URL 里写了完整请求 URL。各 Agent 会自己拼后缀，从 base URL 里去掉它。 |
| Claude Code 弹出 Anthropic 账号登录 | 这个进程里没有环境变量。彻底退出终端，从已导出变量的 shell 里重开。 |
| Codex 或 Grok Build 没用上你配的 provider | provider 写进了项目级配置文件。移到 ~/.codex/config.toml 或 ~/.grok/config.toml。 |
| 想用另一种协议的模型 | Agent 与模型的协议不一致。见「安装 kie-chat-agents」页的协议不一致时一节。 |
调试
claude --debug 会打印实际发出的请求。codex doctor 会报告加载到的配置以及 provider 是否可达。RUST_LOG=debug GROK_LOG_FILE=/tmp/grok.log grok 会写下请求轨迹。