cliproxy-image-cli

English

可安装的 Codex 原生图片 CLI。它会自动复用本机 Codex 的 OpenAI 兼容配置，把图片生成与图片编辑能力直接带到命令行。

项目亮点

• Codex 原生复用：自动读取本地 Codex 的 base_url 与 OPENAI_API_KEY
• 双命令覆盖：同时支持 generate 与 edit
• 多种输入来源：支持本地文件、URL、data: 图片输入
• 本地文件友好：支持单文件输出、目录输出、覆盖保护与 metadata 导出
• 自动链路选择：同一上游成功过的接口会被记住，后续优先走成功链路
• 面向 CLI 工作流：适合终端脚本、Codex skill、自动化流程直接调用

功能性

• generate：调用 /v1/images/generations
• edit：调用 /v1/images/edits
• 自动发现 Codex 配置与认证信息
• 自动处理本地图片到 data: URL 的转换
• 当上游图片接口不可用时，可回退到 /v1/responses
• 支持保存原始响应相关 metadata

运行要求

• Node.js 18+
• 本机已安装 Codex
• Codex 已配置可用的 OpenAI 兼容上游
• 上游服务可访问，且至少支持以下其一：
  • /v1/images/*
  • /v1/responses 图片生成/编辑链路

安装方式

npm

npm install -g cliproxy-image-cli

Homebrew

brew tap noooob-coder/tap
brew install cliproxy-image-cli

快速开始

CLI 默认会从本机 Codex 目录读取：

~/.codex/config.toml
~/.codex/auth.json

所以正常使用时，不需要手动传 base URL、端口或 API key。

生成图片

cliproxy-image-cli generate \
  --output ./astronaut-cat.png \
  --size 1024x1024 \
  --quality high \
  "一只戴着宇航员头盔的电影感橘猫"

编辑图片

cliproxy-image-cli edit \
  --image ./input.png \
  --mask ./mask.png \
  --output ./edited.png \
  "保留主体不变，把背景替换成雪山"

同时保存 metadata

cliproxy-image-cli \
  --metadata-path ./request.json \
  generate \
  --output ./result.png \
  "日出时分的水彩风景"

如果省略 --output，CLI 会默认把图片保存到当前工作目录，并自动使用清晰的默认文件名，避免直接覆盖已有文件。分辨率策略参考 imagegen：默认 1024x1024，可选 1024x1024、1536x1024、1024x1536 或 auto。

架构图

flowchart LR
    user[用户 / Codex Skill]
    cli["cliproxy-image-cli
bin/cliproxy-image-cli.js"]
    parser["参数解析与命令分发
generate / edit / 全局参数"]
    codex["本地 Codex 配置发现
~/.codex/config.toml
~/.codex/auth.json"]
    inputs["输入规范化
prompt / image / mask / output"]
    adapter["图片 API 适配器"]
    direct["直连图片接口
/v1/images/generations
/v1/images/edits"]
    fallback["Responses 回退
/v1/responses"]
    upstream["OpenAI 兼容上游"]
    decode["响应解析
b64_json / data URL / output item"]
    save["本地保存
files / metadata / summary"]

    user --> cli
    cli --> parser
    parser --> codex
    parser --> inputs
    codex --> adapter
    inputs --> adapter
    adapter --> direct
    adapter -. 回退 .-> fallback
    direct --> upstream
    fallback --> upstream
    upstream --> decode
    decode --> save

命令说明

全局参数

• --timeout <seconds>：请求超时秒数，默认 300
• --metadata-path <file>：把保存结果与响应信息写入 JSON
• --overwrite：允许覆盖已有输出文件

generate

cliproxy-image-cli generate [options] [--output <file|dir>] <prompt>

可选参数：

• --model <name>：默认 gpt-image-2
• --prompt-file <file>
• --output <file|dir>
• --size <WxH>：1024x1024|1536x1024|1024x1536|auto（默认 1024x1024）
• --quality <value>
• --background <value>
• --moderation <value>
• --partial-images <count>
• --output-format png|jpeg|webp
• --response-format b64_json|url

edit

cliproxy-image-cli edit [options] --image <path|url> [--output <file|dir>] <prompt>

可选参数：

• --image <path|url>：可重复，必填
• --mask <path|url>
• --output <file|dir>
• 其余生成共享参数同 generate
• --input-fidelity <value>

自动发现机制

CLI 按以下顺序解析运行时凭据：

1. 优先读取 CODEX_HOME，否则使用 ~/.codex
2. 从 config.toml 中读取当前 model_provider 及其 base_url
3. 从 auth.json 中读取 OPENAI_API_KEY

如果 Codex 指向的是一个暴露 /v1 的 OpenAI 兼容上游，那么 CLI 会自动把图片请求映射到：

• .../v1/images/generations
• .../v1/images/edits

用户无需关心端口或 base URL。

接口偏好缓存

如果某个上游只有一条链路真正可用：

• 直连图片接口：/v1/images/generations / /v1/images/edits
• 或 Responses 回退：/v1/responses

CLI 会把这次成功的传输方式缓存到：

~/.codex/cliproxy-image-cli-preferences.json

后续同一个 base_url 下的同类请求会优先直走上一次成功的接口，而不是每次都重新探测两条链路。

缓存规则：

• 按 base_url + generate/edit 分开记录
• generate 与 edit 各自记忆自己的成功路径
• 如果缓存的首选路径后来失效，CLI 仍会自动尝试另一条路径并刷新缓存

故障排查

如果自动发现成功，但当前 Codex 上游并没有真正实现图片接口，CLI 会输出更明确的诊断信息，包括：

• 发现到的 Codex base URL
• 实际调用的图片端点
• 当前模型名
• 上游返回的错误文本

典型输出示例：

Error: The local Codex configuration was discovered successfully, but the current upstream provider does not support image generation.
Base URL: http://your-provider/v1
Endpoint: http://your-provider/v1/images/generations
Model: gpt-image-2
Upstream response: upstream did not return image output
Action: point Codex at an OpenAI-compatible provider that implements the image endpoints.

如果看到这类报错，通常说明：

• CLI 本身工作正常
• 当前需要调整的是 Codex 的 model_provider / base_url
• 目标上游应支持 /v1/images/* 或 /v1/responses 图片链路