故障排除

本页整理使用献丑 CLI 时最常见的问题。

缺少项目 ID

如果看到下面的错误：

Missing project id. Pass --project-id or set XIANCHOU_PROJECT_ID.

说明命令没有拿到项目 ID。你可以任选一种方式提供：

xianchou models image --project-id <PROJECT_ID>
xianchou models video --project-id <PROJECT_ID>

或保存默认项目：

xianchou auth login --key <ACCESS_KEY> --project-id <PROJECT_ID>

也可以使用环境变量：

export XIANCHOU_PROJECT_ID=<PROJECT_ID>

缺少 Access Key

Access Key 用于认证 CLI 请求。请先在献丑 Web 的头像菜单中创建 Access Key，然后执行：

xianchou auth login --key <ACCESS_KEY>

在 CI 或 Agent 环境中，更推荐通过环境变量注入：

export XIANCHOU_ACCESS_KEY=<ACCESS_KEY>

配置没有生效

环境变量优先于配置文件。如果你已经修改了 ~/.xianchou/config.json，但 CLI 仍然使用旧值，请检查当前 shell 中是否设置了这些变量：

echo $XIANCHOU_ACCESS_KEY
echo $XIANCHOU_PROJECT_ID
echo $XIANCHOU_API_URL
echo $XIANCHOU_CONFIG_DIR

默认配置文件路径是：

~/.xianchou/config.json

如果设置了 XIANCHOU_CONFIG_DIR，CLI 会改用该目录下的 config.json。

不确定模型参数

不要猜测 provider_id、model_id 或 channel。先查看模型目录：

xianchou models image
xianchou models video

如果 generate image、generate video 或 markdown images 没有显式传入模型参数，CLI 会尝试使用模型目录中的默认值。

视频模式参数不完整

视频命令会根据 --mode 校验必需参数：

模式	必需参数
text	非空 --prompt
first	--first-frame-url 或 --first-image-url
first-last	首帧和尾帧 URL
reference	--reference-url、--image-urls 或 --video-urls

如果没有传 --mode，CLI 会根据参考素材自动推断模式。推断结果不符合你的预期时，请显式传入 --mode。

Markdown 没有写回

xianchou markdown images 默认只输出结果，不会修改原文件。要写回 Markdown，需要传入 --write：

xianchou markdown images ./article.md --count 3 --write

如果希望生成封面图并写入 frontmatter，还需要加上 --cover。