Wawapi Image MCP

English｜简体中文

Wawapi Image MCP让使用纯文本模型API的Codex生成、编辑并显示图片。图片字节由本地stdio MCP处理，Codex只接收结构化文本、本地路径和Markdown，因此主模型API不需要原生图片能力，也不需要接收MCPimage内容块。

本项目是独立的社区集成，不是Wawapi、OpenAI或Codex的官方项目。使用者需要自行取得合法有效的Wawapi API Key，并遵守渠道条款、内容政策和计费规则。

三步安装（Windows）

安装前准备

• Windows 10或Windows 11。

• 已经可以正常打开Codex，且终端中可以使用codex命令。

• 一个已开通图片服务的Wawapi API Key。

• 能访问Node.js官方网站和Wawapi的网络连接。

不需要预装Node.js、npm或PowerShell 7，也不需要管理员权限。install.cmd会优先使用pwsh；电脑没有pwsh时，自动使用Windows自带的Windows PowerShell 5.1。安装器会把固定版本的Node.js官方便携运行时放进本项目安装目录，不修改系统PATH。

开始安装

1. 从GitHub Releases下载Wawapi-Image-MCP-v<version>.zip。

2. 解压ZIP，不要直接在压缩包预览窗口中运行文件。

3. 在解压后的文件夹里双击install.cmd，按提示输入API Key。首次安装会自动下载并校验受管Node.js运行时，请保持窗口和网络连接，直到显示“安装完成”。

4. 完全关闭并重新打开Codex，然后新建一个任务。

安装器不会显示或记录完整Key。Windows如果阻止脚本，请先确认ZIP来自本项目Release并完成SHA-256校验；不要运行来源不明的副本。

第一次生成

在新的Codex任务中输入：

使用$wawapi-image生成一张1024×1024 PNG：白色背景上的红色纸鹤，居中构图，柔和阴影，不要文字。生成后把图片显示在对话中。

Codex应先检查MCP，再生成、保存并在对话中显示图片。2K、4K、特殊比例、非PNG、多图或参考图请求会先查询能力证据。

常见安装问题

Related MCP server: RunPod Image MCP Server

项目组成

本仓库只提供两个用户能力：

• wawapi-image MCP：调用Wawapi图片接口、保存结果并返回纯文本工具响应。

• $wawapi-image Codex Skill：指导Codex检查环境、选择工具、控制计费、解释降级并显示本地图片。

install.cmd只是Windows安装入口。仓库不提供网页、桌面程序、EXE、图形界面或独立图片CLI。

适用范围

适合以下场景：

• Codex使用的主模型API只支持文本，但Codex宿主能够调用本地MCP工具。

• 主模型不能接收图片工具结果，但可以读取工具返回的文本和文件路径。

• 需要通过自然语言完成文生图、参考图转换、文件保存和对话内回显。

以下场景不适用：

• Agent或宿主完全不支持MCP工具调用。

• 需要主模型直接理解图片视觉内容。本MCP能验证文件格式和尺寸，但不会赋予文本模型视觉能力。

• 需要任意OpenAI-compatible Base URL。本项目将接口固定为https://wawapii.com/v1，防止Key被配置重定向。

• 需要非Windows的一键安装。MCP运行时代码可跨平台，但当前安全安装器只正式支持Windows 10和Windows 11。

工作原理

用户请求图片
  -> Codex加载$wawapi-image
  -> Codex调用本地stdio MCP
  -> MCP请求Wawapi图片接口
  -> MCP验证并保存真实图片文件
  -> MCP返回纯文本JSON、绝对路径和Markdown
  -> Codex在对话中显示本地文件

MCP成功和失败响应都只包含text内容块。图片Base64不会进入对话上下文。

安装器做什么

安装器会校验内部npm包，下载固定的Node.js v24.19.0 LTS官方便携ZIP并核对内置SHA-256，以掩码方式读取Key，用Windows ACL保护配置，安装Skill，注册MCP，把Codex的该MCP工具超时设为600秒并反读验证，然后通过真实stdio会话执行只读Doctor。运行依赖已经打进Release中的npm包，安装时不会再从npm仓库解析或下载依赖。Codex默认MCP工具超时为60秒，真实生图可能超过该时间，因此这一步不能省略。

Codex官方配置参考将mcp_servers.<id>.tool_timeout_sec定义为覆盖默认60秒工具超时的设置。本项目只修改wawapi-image自己的配置段。

默认安装位置是D:\CodexTools\wawapi-image-mcp；没有D盘时使用%LOCALAPPDATA%\CodexTools\wawapi-image-mcp。受管Node.js位于该目录的runtime子目录，MCP启动器始终显式调用它，因此电脑没有Node.js、只有旧版Node.js或PATH尚未刷新都不影响使用。安装器不会修改用户PATH。

安装器只更新空目录、带有效所有权标记的安装目录，或可确认属于旧版本的安装目录；不会覆盖或卸载无法确认归属的普通目录。

命令行安装与校验（高级）

Release同时提供Wawapi-Image-MCP-v<version>.zip.sha256。解压前可以核对：

Get-FileHash -LiteralPath .\Wawapi-Image-MCP-v1.3.0.zip -Algorithm SHA256
Get-Content -LiteralPath .\Wawapi-Image-MCP-v1.3.0.zip.sha256

install.cmd支持把参数继续传给安装器：

.\install.cmd -InstallRoot "E:\CodexTools\wawapi-image-mcp"

在受限网络中，也可以预先从Node.js官方网站下载与本机架构匹配的node-v24.19.0-win-x64.zip或node-v24.19.0-win-arm64.zip，再让安装器校验并使用本地副本：

.\install.cmd -NodeRuntimeArchive ".\node-v24.19.0-win-x64.zip"

安装器固定接受的官方SHA-256如下：

也可以直接使用系统自带的Windows PowerShell：

powershell.exe -NoLogo -NoProfile -ExecutionPolicy Bypass -File .\install.ps1 `
  -InstallRoot "E:\CodexTools\wawapi-image-mcp"

自定义安装目录的末级名称必须是wawapi-image-mcp，完整路径不能超过100个字符。直接运行install.ps1时结果为JSON；双击入口使用适合人工阅读的结果。

MCP工具

generate_image和edit_image返回data.result.images[]。每项包含：

• path：绝对本地路径。

• file_uri：标准文件URI。

• markdown：可直接回显的Markdown。

• width、height和size：从文件内容识别的真实像素。

• format：从文件头识别的真实格式。

• bytes和sha256：完整性信息。

status=exact表示数量、尺寸和格式全部匹配请求；status=degraded表示文件有效，但至少一项发生降级，必须查看deviations并按实际结果描述。

正确理解Doctor

• ready=true表示本地MCP具备尝试一次用户已授权生图请求的条件，不代表上游生成渠道一定健康。

• catalog_status=verified只证明/models只读目录响应成功。

• catalog_status=unverified是非阻断状态，可能来自DNS、代理、TLS、超时、网关错误或目录接口自身误报。此状态不能写成“生图渠道不可用”。

• Doctor不发送可能计费的生成请求，因此generation_channel_status固定为not_probed。

• 只有generate_image或edit_image从generation_submit、edit_submit或generation_poll阶段返回upstream_channel_unavailable，才构成真实生图渠道不可用的证据。

• Doctor通常很快完成，不能验证长耗时生图是否会被宿主提前终止。最新版安装器会单独把Codex的tool_timeout_sec设为600并反读验证。

模型与输出边界

随仓库发布的能力快照记录截至2026-08-04的实测结果。它是时间点证据，不是永久服务承诺。

• 文生图auto优先gpt-image-2-high。

• 参考图auto优先gpt-image-2。

• 用户显式指定模型时不会静默切换。

• gpt-image-2-high、gpt-image-2-medium和gpt-image-2-low已有1024×1024、2048×2048和3840×2160精确文生图证据。

• 基础gpt-image-2曾把2048×2048降为1254×1254；2026-08-04两次最新真实3840×2160请求均返回2048×1152，历史也曾返回1672×941或精确4K。保持比例不等于达到请求分辨率。

• 输出支持PNG、JPEG和WebP，但上游可能忽略格式；MCP始终按真实文件头保存和报告。

• 单次数量为1到4。上游可能把多图请求降为较少文件或拼图，必须检查actual_count。

• 同一基础模型的count=2、1024×1024、JPEG请求在2026-08-04先返回1张1254×1254 PNG，后返回2张独立1024×1024 PNG；多图数量和像素会波动，两次都发生JPEG到PNG的格式降级。

• 多图请求调用explain_image_capability时必须传入count；返回的requestedCount、expectedCountStatus和证据中的actualCount会明确区分单图与多图能力。

• selection_scope=current_catalog是当前目录感知选择；offline=true得到的bundled_baseline只是历史证据。两者模型不同时，不能把历史模型写成当前auto结果。

• 参考图支持PNG、JPEG和WebP，最大10 MB。

• 一次HTTP502/503/524只表示瞬时状态，不能证明模型永久不支持某项能力。

完整的模型、尺寸、比例、格式和参考图证据见完整能力与降级表。

错误契约

“Key无效”“模型目录未验证”“网络连接失败”和“真实生图渠道不可用”是四种不同状态。MCP会保留探测阶段、目标路径、尝试次数、HTTP状态、网络分类和安全的底层错误码，避免把目录或本机网络问题误判成生图渠道故障。

MCP error -32001: Request timed out是Codex宿主在MCP返回前停止等待，不是上述MCP错误契约中的upstream_timeout。最新版安装器会按Codex官方支持的tool_timeout_sec配置将该MCP设为600秒；若仍出现此消息，不要把它写成渠道不可用，也不要未经重新授权就再次提交可能计费的请求。

安全、隐私与计费

• Base URL固定为https://wawapii.com/v1，配置文件和环境变量都不能更改它。

• MCP优先读取受ACL保护的状态配置；仅在配置不存在时读取WAWAPI_API_KEY，永远不读取OPENAI_API_KEY。

• 安装包、源码、工具响应和日志不应包含Key、Authorization头、图片Base64或完整上游响应。

• 提示词和参考图会发送给Wawapi。若上游返回图片URL，MCP会从该公开地址下载结果，并拒绝本机、私网、链路本地地址和不安全重定向。

• 项目没有遥测。运行时网络请求仅用于Wawapi模型/图片接口和上游返回的公开图片下载地址。

• 安装器只从固定的Node.js官方HTTPS地址下载受管运行时，并对x64/arm64归档使用内置SHA-256校验；校验失败即停止。

• 用户明确请求生成或编辑图片，只代表授权一次可能计费的调用，不代表授权额外变体或无限重试。

• MCP最多只在上游明确表示尚未接单时安全重试一次，例如限流或没有可用渠道。

• 普通502/503/524、网络中断、本地超时和宿主取消不会自动重放。

• 输出目标已存在时会创建不冲突的新文件名，不覆盖用户文件。

不要把Key写入Codex项目、config.toml、README、Issue或聊天记录。若Key曾被公开，立即在渠道侧撤销或轮换。

更新、修改Key与卸载

更新时解压新版本并再次双击install.cmd。安装器会验证发布包、保留现有Key、更新MCP和Skill，然后再次执行只读自检。

修改Key：

.\install.cmd -ResetApiKey

卸载：

.\install.cmd -Uninstall

卸载器只删除可确认属于本项目的安装目录、MCP注册和Skill联接。安装目录中的受保护Key会一并删除，无法从项目恢复。

常见问题

Codex中没有图片工具

打开新的Codex任务。仍不可用时运行codex mcp list并确认存在wawapi-image；缺失时重新运行安装器。

image_doctor返回ready=false

查看issues或安装器的doctor_issues。ready=false一定会附带至少一个阻断项，常见原因是Key缺失、Key明确鉴权失败或本地运行时损坏。最新版安装器会自行配置Node.js，不需要另开任务手工安装Node.js。

image_doctor显示模型目录未验证

查看顶层warnings中的probe_error。其中会标明phase、target_path、attempts、status、network_category和cause_code。这是非阻断状态；Doctor没有调用真实生图接口，不能据此判断渠道不可用。若用户已经明确请求图片，Skill应继续一次真实生成。

生成成功但对话中没有图片

要求Codex使用返回的images[].markdown显示文件。只报告“生成成功”而不显示或链接文件，属于未完成。

生图约60秒后超时

如果消息是MCP error -32001: Request timed out，说明Codex仍在使用默认或旧的宿主超时配置。重新运行最新版install.cmd，检查安装摘要中的MCP工具超时为600秒且已验证，然后完全退出并重新打开Codex。上一次请求是否已被上游接收或计费无法从宿主超时判断，因此不要自动重试。

文本模型能判断图片画得是否正确吗

不能。inspect_image只能验证文件头、尺寸、格式、字节数和SHA-256。没有视觉输入能力的模型必须把文件验证与视觉审查明确区分。

从源码验证和构建

以下命令只面向贡献者；使用GitHub Release双击安装的用户不需要系统Node.js或npm。

npm ci
npm test
npm pack --dry-run
npm run build:release

发布物生成在release目录，包括版本化ZIP、ZIP的独立SHA-256文件和内部文件校验表。离线测试不需要Key，也不会调用Wawapi。verify:live会产生真实图片请求，可能计费，只有Key所有者明确授权时才能运行。

贡献前请阅读CONTRIBUTING.md，安全问题按SECURITY.md私下报告。版本变化见CHANGELOG.md。

许可证

代码以MIT License开源。Wawapi、OpenAI、Codex及相关模型名称归各自权利人所有；本许可证不授予第三方商标权，也不改变外部服务条款。