Local Codex + MCP Image Agent Demo

这是一个本地运行的图片生成 Demo，完整调用链为：

React → FastAPI → Codex CLI → STDIO MCP generate_image → OpenAI-compatible 中转 API → 本地存储

项目只包含单用户本地原型需要的功能：提交提示词、异步查询状态、预览和下载图片。它不包含登录、计费、历史记录、图片编辑或多用户并发。

环境要求

• Python 3.13+

• Node.js 20+

• 已安装并登录的 Codex CLI

• 支持 POST /images/generations 的 OpenAI-compatible 图片中转 API

Related MCP server: image-forge-mcp

安装

在项目根目录执行：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env

编辑 .env，至少填写：

IMAGE_API_BASE=https://relay.example.com/v1
IMAGE_API_KEY=your-local-key
IMAGE_MODEL=gpt-image-2

真实 .env 已被 Git 忽略。不要把 Key 写进 .codex/config.toml、前端代码或日志。

安装前端依赖：

Set-Location frontend
npm install
Set-Location ..

分层验证

先绕过 Codex 和 MCP 验证中转 API：

python scripts/test_relay_api.py

成功后，图片会保存到 data/generated/test-output.<格式>。

项目级 .codex/config.toml 已配置 image_generator STDIO MCP。项目被 Codex 信任并激活虚拟环境后，可检查连接：

codex mcp list
codex

进入 Codex TUI 后使用 /mcp，确认存在 image_generator 和 generate_image。也可以要求：

使用 image generator MCP 工具生成一张蓝白色科技风海报。

启动

终端一，启动后端：

激活后，提示符前会出现 (.venv)

python -m pip install -e ".[dev]"

启动后端

python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --reload

python -m uvicorn backend.app.main:app --host 127.0.0.1 --port 8000 --reload

终端二，启动前端： Set-Location d:\project\image-2-Agent\frontend

Set-Location frontend
npm run dev

浏览器打开 http://127.0.0.1:5173。

API

• POST /api/generations：创建任务，返回 job_id

• GET /api/generations/{job_id}：查询任务状态

• GET /api/images/{image_id}：预览图片

• GET /api/images/{image_id}/download：下载图片

• GET /api/health：健康检查

任务状态保存在内存中，服务重启后会丢失。图片和元数据分别保存在 data/generated 与 data/results。

测试与构建

pytest
Set-Location frontend
npm run build

Provider 和后端测试全部使用 mock，不会请求真实中转 API，也不会产生图片费用。真实端到端测试必须由本机已登录的 Codex 和有效中转 Key 完成。

常见错误

• codex_not_found：后端账号找不到 Codex CLI。

• codex_not_authenticated：先在同一操作系统账号下登录 Codex。

• mcp_unavailable：检查虚拟环境、项目信任和 .codex/config.toml。

• provider_auth_failed：检查 API Base、Key 和模型别名。

• provider_rate_limited：请求过于频繁，稍后重试。

• provider_quota_exhausted：中转 API 免费额度已用完，请充值或更换模型。

• provider_unavailable（no_available_channel）：免费模型通道暂不可用，可改用 gpt-image-2 或稍后重试。

• provider_auth_failed：检查 API Key 是否来自当前平台，修改 .env 后需重启后端。

• provider_timeout：提高 IMAGE_API_TIMEOUT_SECONDS 或检查中转服务。

• tool_not_called：Codex 没有实际调用 generate_image，结果会被拒绝。

• mcp_tool_cancelled / user cancelled MCP tool call：Codex exec 在 read-only 沙箱下会取消 MCP 工具调用。将 .env 中 CODEX_SANDBOX 设为 danger-full-access。

• provider_invalid_response（404 Invalid URL）：IMAGE_API_BASE 应填写到 /v1，不要包含 /images/generations。