openclaw-voc-skill/claude-code/fmode-image-set/docs/troubleshooting.md

Troubleshooting

Skill 能触发但看不到 MCP Tool

重新运行工作区安装，检查工作区 .mcp.json 中 cwd 和 Server 路径是否为实际绝对路径，然后重启 Claude Code。

needs_token

为 Claude Code/MCP 进程配置 FMODE_LLM_API_KEY 或 LLM_API_KEY。不要把 Key 写入仓库。

远程 HTTP 被阻断

API Key 会在 HTTP 连接中明文传输。优先要求网关提供 HTTPS；如果目标是明确受信的内网网关，设置 FMODE_ALLOW_INSECURE_HTTP=true 后重启 MCP。

[Unsupported Image]

不要让 Skill Glob 或猜测历史图片。首选把商品图保存到当前项目内，并在对话中粘贴图片的显式绝对路径或相对路径。带精确 sessionId + promptId + cwd 的旧附件解析仅作为兼容回退。

submission_unknown

请求是否已被网关接收无法确定。执行器会为当前 outputId 使用同一稳定幂等键最多自动尝试三次；耗尽后记录该项并继续后续图片，不自动切换模型。任务结束后保留 runId，只询问是否重试失败 outputId；确认后在原 run 续跑，不重新规划整套。

quality_rejected / unverified

• quality_rejected：Gemini 发现身份漂移或明显质量问题；文件仍会保留，但不会作为主图锚点。
• unverified：Gemini Key、服务或结构化响应不可用；不能当作质量通过，需人工复核。

状态查询

当前 New API 链路同步返回图片，不再轮询旧即梦 workId。fmode_image_set_status 默认读取脱敏本地状态；若响应已持久化远程结果 URL，可用 refresh=true 恢复下载，但不会再次调用生图接口。

输出路径被拒绝

新输出根目录固定为调用方项目的 输出/商品套图/，不能由 Tool 参数改写，也不能经过符号链接写入 Skill 源码、其他运行目录或项目外路径。旧 outputs/fmode-image-set/ 仅用于读取既有运行。