# 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 会优先调用视觉 Tool，附件解析器会从当前 Claude 请求中定位图片。若仍失败，传入当前项目内图片的显式绝对路径。

## `submission_unknown`

请求可能已被网关接收并计费。执行器会停止后续付费请求，不自动重提，也不自动切换到另一个模型。保留 `run_id`，通过网关日志或支持渠道人工核验后，再由用户明确授权下一步。

## `quality_rejected` / `unverified`

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

## 状态查询

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

## 输出路径被拒绝

输出根目录固定为调用方项目的 `outputs/fmode-image-set/`，不能由 Tool 参数改写，也不能经过符号链接写入 Skill 源码、其他运行目录或项目外路径。