AI教程

乔木 Codex 生图教程：让 Claude、Cursor 与任意 Agent 先选风格再生成图片

本教程将带你安装 qiaomu-codex-imagegen，并通过 Agent、MCP 和命令行完成风格推荐、提示词编排、图片生成、改图与结果验收。

AI我搜编辑部2026年10月4日阅读约 12 分钟

乔木 Codex 生图教程：让 Claude、Cursor 与任意 Agent 先选风格再生成图片

项目简介

qiaomu-codex-imagegen 将 Codex 内置的图片生成能力封装为 MCP 服务、命令行工具和 Agent Skill。安装后，Claude Code、Codex、Cursor 或其他能够执行命令的 Agent，都可以根据自然语言请求生成图片文件。

它与普通的“直接输入一句提示词并出图”不同：默认会先通过 suggest_directions 推荐至少四个机制不同的风格方向，用户选定方向后，再由 compose_prompt 展开完整提示词，最后生成并检查结果。

项目内置 24 类场景模板、48 个预设、66 种通用风格和 20 位 Mondo 海报设计师风格，还提供一套针对文字、事实、构图和验收的规则，适合制作封面、海报、社交媒体配图、产品视觉和参考图改图。

核心工作流程

推荐方向：根据主题和使用场景，返回至少四个机制不同的方向，例如文字主导、平面结构、摄影人物、产品近摄或材料空间。
选择方向：用户可以选择一个或多个方向，也可以让 Agent 自己决定；如果不满意，还可以排除已有方向后再次推荐。
展开提示词：将模板变量填入完整提示词，并同时给出避免项、验收条件、假设和缺失信息。
生成图片：每个选中的方向生成一张图片，并在图片旁保存实际使用的 JSON 信息，便于复现和制作系列内容。
验收与重做：Agent 根据验收条件逐项检查图片，不合格时只修改对应部分，再生成一次。

如果用户已经明确指定了风格，例如“使用 Mondo 风格”或直接提供 T03，系统可以跳过方向选择，直接进入提示词编排或生成阶段。

安装前准备

使用前需要准备以下环境：

Node.js 18 或更高版本：可以通过 node --version 检查。
Codex CLI：需要安装并登录，使用 codex --version 确认命令可用。
图片生成权限：当前 Codex 账号必须能够使用图片生成。建议先在 Codex 中手动生成一张图片进行验证。

项目本身为零依赖 Node.js 项目，但真正的图片生成仍依赖本机可用的 Codex CLI 和账号额度。

安装 Agent Skill

如果使用的 Agent 支持 Agent Skills，可以直接执行：

npx skills add joeseesun/qiaomu-codex-imagegen

Skill 会帮助 Agent 理解场景选择、风格选择、描述编写和验收方式，并通过 MCP 或项目自带的命令行工具生成图片。

注册 MCP 服务

在 Claude Code 中注册

将下面的路径替换为项目实际所在目录：

claude mcp add --scope user qiaomu-codex-imagegen -- node /绝对路径/qiaomu-codex-imagegen/scripts/mcp-server.mjs

在其他 MCP 客户端中配置

Cursor、Codex 或其他 MCP 客户端可以在配置文件中加入：

{
  "mcpServers": {
    "qiaomu-codex-imagegen": {
      "command": "node",
      "args": ["/绝对路径/qiaomu-codex-imagegen/scripts/mcp-server.mjs"]
    }
  }
}

MCP 服务提供七个工具：

suggest_directions：免费即时推荐至少四个机制不同的风格方向。
compose_prompt：将模板和预设展开为完整提示词，并返回避免项、验收条件和缺失信息。
generate_image：生成新图片或执行参考图改图，并返回文件路径和像素尺寸。
search_prompts 与 get_prompt：检索和读取本地参考提示词语料。
build_prompt：预览简易路线生成的提示词，但不实际出图。
list_catalog：查看场景预设、模板、风格键和本地语料状态。

只使用命令行

如果不需要 MCP，也可以直接克隆仓库并运行 CLI：

git clone https://github.com/joeseesun/qiaomu-codex-imagegen
cd qiaomu-codex-imagegen
node scripts/cli.mjs "窗边翻开的书，书页上升起咖啡的热气" --preset xiaohongshu

默认生成的图片会保存到 ~/Pictures/qiaomu-codex-imagegen/<日期>。也可以通过 --out、--name 和 --json 控制输出目录、文件名和机器可读结果。

基础用法：先推荐方向

建议在海报、封面和社交媒体配图任务中，优先使用“先推荐、后生成”的流程。下面的命令会为“咖啡店阅读活动”推荐多个方向，但不会消耗图片生成额度：

node scripts/cli.mjs suggest "一个月的咖啡店阅读活动" --for 视频封面

返回结果通常会说明每个方向的视觉机制、风格锁、需要补充的信息和参考案例。你可以选择一个方向，也可以要求 Agent 并行生成多个方向进行比较。

展开模板提示词

确定方向后，可以先查看完整提示词和验收条件：

node scripts/cli.mjs compose --template T03-1 --var topic=谷雨 --var subject=嫩芽 --var headline=谷雨

模板会根据变量生成结构化描述。除了主体和风格，还可能包含文字层级、留白、安全区、失败条件和检查标准。先查看提示词，有助于在正式生成前发现变量缺失或文案过长的问题。

使用模板生成图片

确认提示词无误后，可以直接生成：

node scripts/cli.mjs generate --template T03-1 --var topic=谷雨 --var subject=嫩芽 --var headline=谷雨

项目包含 24 类模板，例如巨字与微小叙事、物象破框、中央光隙、东方水墨编辑、纸雕与织物地貌、摄影肖像、食品近摄、科技产品主视觉、建筑制图和信息卡等。不同模板不仅改变颜色或滤镜，而是改变构图机制、材料关系、文字层级和主体之间的关系。

使用预设和风格快速生成

如果已经知道场景和风格，可以采用简易路线，不经过方向推荐。例如生成三个视频封面方案：

node scripts/cli.mjs "一个巨大的红色播放键像日出一样升起" --preset video-cover --style saul-bass --count 3

常用场景预设包括：

xiaohongshu 和 xiaohongshu-square：小红书 3:4 或方形封面。
video-cover：YouTube、B 站等 16:9 横版封面。
video-vertical：抖音、视频号和 Reels 的 9:16 竖版封面。
wechat-cover：公众号 2.35:1 头图。
x-cover：X 个人页 5:2 封面。
moments：朋友圈 4:5 海报。
poster 和 movie-poster：通用海报与电影海报。
book-cover、album-cover、article 和 paper：书籍、专辑、文章和科普配图。

例如，使用 Mondo 风格制作不带文字的电影海报：

node scripts/cli.mjs "沙漠中巨大的沙虫轮廓，渺小的人影" --preset movie-poster --style olly-moss

控制图内文字

海报和封面通常需要标题、副标题、信息行或角标，而不是只放一个标题。可以使用 --text 指定文字：

node scripts/cli.mjs "一座灯塔" --preset wechat-cover --text "夜航船"

如果包含中文或较长文案，建议逐字提供短句，并在生成后放大检查。项目说明指出，模型生成中文和小字号信息行时仍可能出现细微错误；肖像或不需要信息层的产品近摄则可以使用无字方案。

参考图改图

通过 --ref 可以提供一张或多张参考图。参考图路径必须是绝对路径：

node scripts/cli.mjs "保持同一支铅笔，背景换成暖米色纸张" --ref /abs/pencil.png --ratio 1:1

这种方式适合替换背景、保持主体不变或进行局部视觉调整。项目不会静默裁剪图片，如果最终比例与要求不符，结果中会标明尺寸差异。

提示词预览与本地案例检索

只想检查提示词而不生成图片时，可以使用：

node scripts/cli.mjs "咖啡和书" --preset xiaohongshu --show-prompt

如果已经构建了可选的本地语料包，还可以检索相似案例：

node scripts/cli.mjs search "节气 茶" --limit 5

语料包包含约 689 条参考提示词及缩略图，但这些第三方数据不随仓库发布。没有语料包时，模板、风格和图片生成流程仍然可以正常使用。

高级配置与实践建议

为系列图片固定方向

制作一组小红书配图或多张封面时，建议先为第一张选择模板和风格，再让后续图片沿用相同的风格锁、比例和信息结构。这样比每张图片单独输入“类似风格”更容易保持一致。

使用并行变体时控制额度

--count 可以并行生成 1 到 4 个变体，但每张图片都会消耗 Codex 或 OpenAI 账号额度。单张图片通常需要约 30 到 60 秒，并行数量越多，消耗也会相应增加。

处理透明背景问题

项目会检测生成结果中的透明区域。默认情况下，检测到透明区域时会压平到白色背景；如果确实需要保留透明背景，可以使用 transparent_background: true。这项处理用于避免部分看图软件将透明区域显示为黑边。

指定 Codex 路径和超时时间

如果系统找不到 Codex，可以通过环境变量 QIAOMU_CODEX_BIN 指定可执行文件路径。生成超时时，可以提高 --timeout 的值，或者先简化描述：

node scripts/cli.mjs "咖啡店阅读活动封面" --preset video-cover --timeout 120000

构建本地语料包

如果你拥有自己的归档目录，并且其中包含 archive.json、prompts/ 和 images/，可以执行：

node scripts/build-corpus.mjs /path/to/提示词归档

默认语料目录为 ~/.local/share/qiaomu-codex-imagegen/corpus，也可以通过 QIAOMU_CORPUS_DIR 指向其他位置。语料包仅建议在本机使用，不要提交或转发未经授权的第三方内容。

验证安装是否成功

项目提供离线测试和目录检查命令：

npm test
node scripts/cli.mjs --list
node scripts/cli.mjs "一个红色圆" --show-prompt

npm test 不会消耗图片生成额度，可用于验证模板组装、文字模式、结构替换、方向多样性、语料检索、透明背景处理和协议等功能。

常见问题

cannot start codex：确认已安装 Codex CLI，或设置 QIAOMU_CODEX_BIN。
codex finished without producing an image：检查 Codex 登录状态和账号是否拥有图片生成权限。
timed out：增加超时时间，或减少描述复杂度。
比例不符合预期：在描述中再次强调比例，或使用 --ratio；工具不会自动静默裁剪。
参考图找不到：将 --ref 的值改为绝对路径。

结语

qiaomu-codex-imagegen 的重点不是简单地把一句话转发给图片模型，而是把场景、风格、构图关系、文字层级和验收标准组织成一条可复用的工作流。你可以从 Agent Skill 或 MCP 开始，让 Agent 负责推荐和编排；也可以通过 CLI 精确控制预设、风格、比例、文字和参考图。

对于需要稳定产出封面、海报和系列配图的任务，推荐采用“先推荐方向、再展开提示词、生成后按条件验收”的流程，并对正式使用的图内文字和尺寸进行人工复核。