@ailuntz/codex-api

把已登录的 Codex 临时包装成本机 /v1/responses HTTP 接口。

curl -> localhost adapter -> existing codex exec --json -> loopback text-only gateway -> provider

安装

curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login
npm install -g @ailuntz/codex-api
codex-api install-service

本包不附带 Codex，也不会再安装一份 Codex。它直接使用电脑里已经安装、已经登录的 codex 命令；可先运行 codex --version 确认。

开关

codex-api status
codex-api stop
codex-api start
codex-api restart
codex-api uninstall-service

curl

本地适配器：

curl http://127.0.0.1:8787/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "input": "只回复 API_OK",
    "stream": false
  }'

连续对话可以把上一轮返回的 id 作为下一轮的 previous_response_id：

curl http://127.0.0.1:8787/v1/responses \
  -H 'Content-Type: application/json' \
  -d '{
    "previous_response_id": "resp_...",
    "input": "继续刚才的话题"
  }'

官方 OpenAI API：

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "gpt-5.2",
    "input": "只回复 API_OK"
  }'

本地适配器默认只监听 127.0.0.1:8787，所以默认不需要 Bearer Key。若改为非本机监听地址，必须在配置中设置 ADAPTER_API_KEY。

配置

codex-api config-path

首次运行会生成适配器自己的服务配置和工作目录，但 Codex 进程直接共用主机的 CODEX_HOME。登录态和本地 session 都使用这个目录；适配器不会再创建独立的 Codex home。

适配器会先从主机 CODEX_HOME/config.toml 读取模型和上游配置，再把必要配置作为单次调用参数传给 Codex。调用使用 --ignore-user-config，避免额外加载主机插件、MCP 和其他用户配置，但认证与 session 落盘仍然使用主 CODEX_HOME。

Codex CLI 会在本地组装完整的代理上下文。适配器的回环网关会在请求离开本机前删除 Codex 内建 developer 上下文与工具合同，只把 API 调用者的 instructions 和 input 发给模型，并设置 tool_choice=none。网关使用适配器现有端口上的随机隐藏路径，只接受本机回调，不会另开监听端口，也不记录认证信息或请求正文。HTTP 与 Responses WebSocket v2 都经过同一套裁剪逻辑。

适配器会按模型和稳定 developer instructions 生成固定的 prompt_cache_key，帮助重复长前缀命中上游缓存。短请求显示 cached_tokens=0 是正常现象：缓存有最小可缓存长度，并且首次请求还没有可复用的前缀。

每次请求仍创建一个全新的本地 Codex thread，thread 会正常保存到主机 CODEX_HOME/sessions，便于审计和排查。若传入 previous_response_id，模型端通过适配器保持的 Responses WebSocket v2 连接续接上下文；不传则创建独立模型响应。

未设置 CODEX_HOME 时使用 ~/.codex。默认配置不会固定保存 home 或 CLI 路径；CLI 自动查找也覆盖 ~/.local/bin/codex，适用于 launchd 的精简 PATH。已有的显式配置仍保留，迁移到默认安装后可删除旧的 CODEX_HOME、CODEX_BIN 设置。

未配置模型时由 Codex CLI 选择默认模型，也可通过请求的 model 或 CODEX_MODEL 指定；此时 /healthz 的模型为 null，/v1/models 返回空列表。

常用可选项：

ADAPTER_HOST=127.0.0.1
ADAPTER_PORT=8787
# CODEX_HOME=/path/to/codex-home
# CODEX_BIN=/path/to/codex
# ADAPTER_API_KEY=replace-with-a-long-random-secret
# CODEX_BASE_URL=https://your-provider.example
# CODEX_MODEL=your-model

限制

• 仅支持文本、非流式 stream=false。
• 支持同一适配器进程内的 previous_response_id；上游要求 WebSocket store=false，适配器或上游连接重启后，旧 response ID 可能失效。
• 不支持 Responses conversation、图片、音频和原生工具调用。
• 每个请求创建独立 Codex thread，并以单并发队列执行。
• 请求不使用 --ephemeral，thread rollout 会保存在主机 CODEX_HOME。
• 请求使用 --ignore-user-config，并由本机回环网关在发送前裁掉 Codex 内建代理上下文和工具合同；服务端只收到精简后的对话请求。
• 这是临时适配器，不是完整的 OpenAI API 实现。

卸载

先停止后台进程并移除 launchd 服务，再卸载 npm 包：

codex-api uninstall-service
npm uninstall -g @ailuntz/codex-api

uninstall-service 也会停止由 codex-api start 启动的独立后台进程；卸载失败会报错，重复执行不会创建新的配置目录。仅执行 npm 卸载不会移除 launchd 服务。

上述操作保留适配器的配置、日志和工作目录。macOS 默认位于 ~/Library/Application Support/codex-api；确认不需要后可以删除此目录完成清理（使用 CODEX_API_HOME 时清理对应目录）。主机的 ~/.codex、登录态及 Codex CLI 不属于本包，不应删除。