手动配置 Codex

提示

Codex 的关键不是只填 API Key，而是 config.toml 和 auth.json 两个文件要同时存在。很多配置失败，都是因为只写了其中一个。

第一步：安装 Codex

如果你主要使用 Codex App，先看第一个标签；如果你主要在终端里使用 Codex，再看 CLI。

如果你还没安装 Codex App，可以从这里下载：

https://developers.openai.com/codex/quickstart?setup=app

提示：打开或下载这个页面时，通常需要先挂 VPN。

npm i -g @openai/codex@latest

提示：运行前需要先安装最新版 Node.js，可从 Node.js 官网 下载。

如果你主要在终端里使用 Codex，先安装 CLI，再继续下面的配置步骤。

如果你准备在 VS Code 中使用 Codex 相关插件，最佳顺序是：

1. 先把本机的 Codex 环境变量或配置文件准备好
2. 确认终端里的 codex 已经能正常调用 Waihub
3. 再安装并打开 VS Code 插件

这样做的好处是，插件层如果出现问题，你可以先排除掉接口、密钥和模型配置问题。

第二步：打开 Codex 配置目录

先打开你的终端程序，然后根据系统运行下面的命令，进入 Codex 的配置目录。

CMD 命令行：

mkdir "%USERPROFILE%\.codex" & rem 仅首次配置需要
start "" "%USERPROFILE%\.codex"

终端命令：

mkdir "$HOME/.codex" # 仅首次配置需要
open "$HOME/.codex"

第三步：创建 config.toml

在 ~/.codex 目录下创建 config.toml：

model = "gpt-5.5"
model_provider = "custom"
model_reasoning_effort = "medium"
disable_response_storage = true

[model_providers.custom]
name = "custom"
base_url = "https://waihub.top/v1"
wire_api = "responses"

推荐做法

如果你后续还会接入别的渠道，可以继续在 config.toml 里新增其它 model_providers.* 段落，然后只切换 model_provider 的值，不必整份文件重写。

第四步：创建 auth.json

然后创建 auth.json，其中 OPENAI_API_KEY 需要去 Waihub Token 控制台 创建：

{
  "OPENAI_API_KEY": "sk-xxxxxxxx"
}

配置结果

当 config.toml 和 auth.json 这两个文件都配置完成后，通常不只是命令行里的 codex 能使用，依赖同一套本地配置的 codex-app 也会自动读取到这些设置。

第五步：启动 Codex 验证

保存后，根据你的使用方式启动 Codex：

• 如果使用的是 Codex App，直接打开 Codex App 即可。
• 如果是 CLI 安装方式，则在终端运行：

codex

启动后如果能正常发起对话，说明配置已生效。

Codex App 直接生图

完成上面的 config.toml 和 auth.json 配置后，Codex App 通常会自动读取同一套本地配置。此时可以直接在 Codex App 里输入生图需求，例如“生成一张产品海报”或“把这张图片改成插画风格”，不需要先手动写接口请求。

Codex App 可直接通过已配置的 Waihub 通道生图。

如果 App 没有读取到新配置，先彻底退出 Codex App，再重新打开。配置变更后不重启，常见现象是仍然走旧模型、旧密钥或旧接口地址。

接口调用生图

如果你想通过 Waihub 的 Responses 接口调用 gpt-5.5 生图，并把返回的 Base64 结果直接保存为 PNG，可以使用下面的方式。命令行方式适合自动化脚本、批量测试，或者需要明确保存响应 JSON 排查问题的场景。

提示

日常使用优先在 Codex App 里直接生图；需要脚本化、批处理或调试接口时，再使用下面的接口示例。

直接生成

curl --location 'https://waihub.top/v1/responses' \
  --header 'Authorization: Bearer sk-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": "画一只可爱的猫抱着水獭"
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "output_format": "png"
      }
    ],
    "instructions": "you are a helpful assistant",
    "tool_choice": "auto",
    "stream": false,
    "store": false
  }' \
| jq -r '.output[]?.result // empty' \
| base64 -D > cat_otter.png

curl --location 'https://waihub.top/v1/responses' \
  --header 'Authorization: Bearer sk-xxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "gpt-5.5",
    "input": [
      {
        "role": "user",
        "content": "画一只可爱的猫抱着水獭"
      }
    ],
    "tools": [
      {
        "type": "image_generation",
        "output_format": "png"
      }
    ],
    "instructions": "you are a helpful assistant",
    "tool_choice": "auto",
    "stream": false,
    "store": false
  }' \
| jq -r '.output[]?.result // empty' \
| base64 -d > cat_otter.png

图像编辑

如果要基于本地图片做编辑，需要先把本地图片转成 data:image/...;base64,...，再作为 input_image 放进请求体。image_generation 工具中设置 action: "edit" 即可进入图像编辑模式。

常见格式对应关系：

.jpg / .jpeg -> image/jpeg
.png         -> image/png
.webp        -> image/webp

:::

测试前需要先安装 jq。macOS 可以使用 Homebrew 安装：

brew install jq

export OPENAI_API_KEY="sk-xxxxxxxx"

IMAGE_PATH="/Users/lwy/Desktop/dd.jpg"

{
  printf 'data:image/jpeg;base64,'
  base64 -i "$IMAGE_PATH" | tr -d '\n'
} > image_data.txt

jq -n --rawfile img image_data.txt '{
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        {
          type: "input_text",
          text: "把这张图修改成：可爱的猫抱着水獭，保留原图主体构图和风格"
        },
        {
          type: "input_image",
          image_url: $img
        }
      ]
    }
  ],
  tools: [
    {
      type: "image_generation",
      output_format: "png",
      action: "edit"
    }
  ],
  instructions: "you are a helpful assistant",
  tool_choice: "auto",
  stream: false,
  store: false
}' | curl --location 'https://waihub.top/v1/responses' \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @- \
| tee response.json \
| jq -r '
  .output[]?
  | select(.type == "image_generation_call")
  | .result // empty
' \
| base64 -D > dd_edited.png

测试前需要先安装 jq。Debian / Ubuntu / WSL 可以运行：

sudo apt update
sudo apt install -y jq

如果当前已经是 root 用户，可以去掉命令前面的 sudo。

export OPENAI_API_KEY="sk-xxxxxxxx"

IMAGE_PATH="/root/dd.jpg"

{
  printf 'data:image/jpeg;base64,'
  base64 -w 0 "$IMAGE_PATH"
} > image_data.txt

jq -n --rawfile img image_data.txt '{
  model: "gpt-5.5",
  input: [
    {
      role: "user",
      content: [
        { type: "input_text", text: "把这张图修改成：可爱的猫抱着水獭，保留原图主体构图和风格" },
        { type: "input_image", image_url: $img }
      ]
    }
  ],
  tools: [
    { type: "image_generation", output_format: "png", action: "edit" }
  ],
  instructions: "you are a helpful assistant",
  tool_choice: "auto",
  stream: false,
  store: false
}' | curl --location 'https://waihub.top/v1/responses' \
  --header "Authorization: Bearer $OPENAI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @- \
| tee response.json \
| jq -r '
  .output[]?
  | select(.type == "image_generation_call")
  | .result // empty
' \
| base64 --decode > dd_edited.png

这套写法的关键点是：

• input 里要放一张 input_image
• tools 里使用 type: "image_generation"、output_format: "png"、action: "edit"
• 测试前需要先安装 jq
• 示例使用 --rawfile 从文件读取 Base64，避免图片太大时触发 Argument list too long
• 不要加 input_fidelity，这个参数在当前兼容链路里会报错
• 如果输出文件是空的，先看 response.json，通常能直接看到错误信息

其它可复用场景

除了命令行本体，这套配置思路在一些相关编辑器场景里也能复用。

在 Cursor 中使用

若其调用链路复用本地 Codex 配置或相同 provider 逻辑，也可以沿用这套接入方式。

在 VS Code 中使用

插件或集成终端若走同一套配置，也可以直接复用。建议先确保本机配置生效，再进入编辑器侧验证。

示例界面

Codex App

Codex App 示例图。两份文件配好后，Codex App 通常也会自动继承同一套配置。

Cursor

Cursor 示例图。若其调用链路复用本地 Codex 配置或相同 provider 逻辑，也可以沿用这套接入方式。

VS Code

VS Code 示例图。