Codex Stack API 完整接入指南

本文是发给最终用户的完整接入文档。用户拿到本文、门户登录凭据和管理员单独发放的 API Key 后，可以通过公网 HTTPS 独立完成以下操作：

• 登录自己的访问账户门户并管理已有 API Key
• Windows Codex Desktop 或原生 Codex CLI
• WSL2、macOS、Linux 中的 Codex CLI
• DeepSeek Harness（DSH）
• 其他 OpenAI-compatible 客户端、curl、Python SDK 和 Node.js SDK
• 附件上传和受信用户的会话归档读取

本文不会包含真实 API Key、账户信息、内网 IP 或服务端运维配置。API Key 应由管理员通过单独的安全渠道发送。

最短接入路径

0. 首次接入与账户门户

开始前需要收到什么

管理员通常会通过安全渠道分别提供：

1. 门户用户名和密码；
2. 一枚或多枚 API Key，以及每枚 Key 对应的设备或用途名称；
3. 必要时提供该账户的使用范围或配额说明。

门户密码和 API Key 不是同一种凭据：门户密码只用于登录网页；API Key 用于 Codex、DSH、SDK 和直接 API 请求。门户不会显示或复制 API Key 原文，因此收到 API Key 后应立即保存到可信的密码管理器。若缺少、遗失或怀疑泄露，请联系管理员重新签发，不要尝试从门户找回原文。

登录账户门户

打开：https://api.meowtis.net/portal

登录后先确认页面显示的访问账户名称正确，再核对 API Key 的用途名称和创建时间。门户只显示当前账户已配置且未删除的 Key，不暴露 Key 原文；Key 是否已到期应以实际连接验证为准。

删除 API Key 不会删除访问账户，也不会删除该账户已有的 Files 或会话归档。同一账户的其他有效 Key 仍能访问这些数据。如果删除的是最后一枚 Key，在管理员重新签发之前将无法调用 API；账户数据仍然保留。

门户登录最长保持 12 小时，服务重启也会让现有登录失效。使用公共或共享设备后请主动点击“退出登录”，不要让浏览器保存门户密码或 API Key。

理解访问账户与 API Key

访问账户是数据和权限边界，API Key 只是该账户的设备凭据：

• 同一访问账户可以拥有多枚 Key，适合为不同设备或客户端分别签发。
• 同一账户下的 Key 共享 Files 和 Session History；轮换 Key 不会迁移或丢失数据。
• 不同访问账户之间严格隔离，不能通过 Header、请求参数或文件 ID 越过边界。
• Key 过期、被删除或所属账户被停用后，请求会返回 401 Unauthorized。

不要在多个不互相信任的人或设备之间共用同一枚 Key。需要隔离数据时，应请管理员创建独立访问账户，而不只是为同一账户多签发一枚 Key。

1. 固定接入信息

公网入口使用受公共信任的 IP 地址证书。

其他常用模型包括 gpt-5.6-terra 和 gpt-5.6-luna。完整列表以 GET /v1/models 的实时返回结果为准。当前明确支持和验证过的接口为：

模型名称与服务等级

客户端必须始终使用与 OpenAI 官方一致的模型名称，例如 gpt-6-astra、 gpt-5.6-sol、gpt-5.6-terra 或 gpt-5.6-luna。不要添加 -fast 等自定义后缀，也不要把内部路由别名登记为客户端模型。非官方名称可能无法匹配 Codex 的原生模型能力目录，导致客户端递交无用的完整工具 Schema，显著增加输入上下文。

当前接入使用 Standard，不开放 Fast。账户额度固定为 $300，余额自动按 $300 减去上次重置后的费用计算。服务主窗口恢复 100% 时自动重置额度，也可联系管理员手动重置；历史费用保留。客户端无需配置服务等级。

本文中的 API Key 是 Codex Stack 网关凭据，不是 OpenAI Platform API Key；本服务的用量统计采用上游 ChatGPT credits 口径，不是 OpenAI Platform 的 API Token 账单。

网络前提与代理绕过

公网地址可从普通互联网直接访问，API Key 仍是必需的应用层凭据。如果客户端或系统启用了 Clash 等 HTTP 代理，建议在启动客户端前让 API 域名直连，避免代理节点改变链路或阻断长连接。

macOS、Linux 或 WSL：

export NO_PROXY="api.meowtis.net${NO_PROXY:+,$NO_PROXY}"
export no_proxy="$NO_PROXY"

Windows PowerShell：

$env:NO_PROXY = "api.meowtis.net,$env:NO_PROXY"

如果需要从开始菜单启动受系统代理影响的 Windows 桌面应用，可把绕过规则也保存为当前用户环境变量，然后重新打开应用：

$userNoProxy = [Environment]::GetEnvironmentVariable("NO_PROXY", "User")
$newNoProxy = @("api.meowtis.net", $userNoProxy) | Where-Object { $_ }
[Environment]::SetEnvironmentVariable("NO_PROXY", ($newNoProxy -join ","), "User")

2. 设置 API Key

不要把 API Key 写进本文、源码、Git 提交或普通配置文件。以下命令在当前终端中安全读取 API Key，并同时设置固定地址和默认模型。

macOS / Linux / WSL：

printf "API Key: "
IFS= read -rs CODEX_STACK_API_KEY
printf "\n"
export CODEX_STACK_API_KEY
export CODEX_STACK_BASE_URL="https://api.meowtis.net/v1"
export CODEX_STACK_MODEL="gpt-6-astra"

Windows PowerShell 7：

$env:CODEX_STACK_API_KEY = Read-Host "API Key" -MaskInput
$env:CODEX_STACK_BASE_URL = "https://api.meowtis.net/v1"
$env:CODEX_STACK_MODEL = "gpt-6-astra"

这些变量只对当前终端会话生效。关闭终端后需要重新设置。WSL 是独立的 Linux 环境，不会自动继承 Windows 用户环境变量，因此必须在 WSL 终端中单独执行上面的 macOS / Linux 命令。

如果要从 Windows 开始菜单启动 Codex Desktop 或 DSH，临时的 $env: 变量不会传给新启动的桌面应用。可在 PowerShell 7 中把密钥设置为当前 Windows 用户变量：

$apiKey = Read-Host "API Key" -MaskInput
[Environment]::SetEnvironmentVariable("CODEX_STACK_API_KEY", $apiKey, "User")
Remove-Variable apiKey

设置后完全退出并重新打开 Codex/DSH。Windows 用户环境变量不是加密的密码库；共享或不受信设备应改用每次启动时临时输入，或使用客户端自己的凭据管理功能。

3. 一分钟连接验证

macOS / Linux：

curl --noproxy "api.meowtis.net" --fail-with-body \
  "$CODEX_STACK_BASE_URL/models" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY"

Windows PowerShell 7：

$headers = @{ Authorization = "Bearer $env:CODEX_STACK_API_KEY" }
Invoke-RestMethod -NoProxy `
  -Uri "$env:CODEX_STACK_BASE_URL/models" `
  -Headers $headers

返回包含 data 的模型列表即表示连接成功。此验证同时检查网络、HTTPS、Base URL 和 API Key。

4. 接入 Codex Desktop 和 Codex CLI

Codex 使用 Responses API。API Key 继续放在 CODEX_STACK_API_KEY 环境变量中，不要把真实密钥写入 TOML。

配置文件路径如下：

Windows 和 WSL 的配置文件与环境变量彼此独立。Provider 配置必须位于用户级配置中，不能只写入项目级 .codex/config.toml。

如果 Codex Desktop 中已有重要任务，修改 Provider 前应先完全退出应用并备份整个 .codex 目录。不要删除或重命名原有 Provider 块；切换默认 Provider 可能影响历史任务在侧边栏中的分组。新安装可以直接使用下面的完整配置。

如果文件中已经存在顶层 model 或 model_provider，请修改原值，不要重复添加同名字段。服务等级在门户或管理后台按 Key 设置，客户端不需要配置 service_tier 或 Fast 功能项。

model = "gpt-6-astra"
model_reasoning_effort = "high"
model_provider = "codex-stack"

[model_providers.codex-stack]
name = "Codex Stack"
base_url = "https://api.meowtis.net/v1"
env_key = "CODEX_STACK_API_KEY"
wire_api = "responses"
supports_websockets = false

本项目网关使用 HTTP/SSE，不提供 Responses WebSocket，因此 supports_websockets = false 必须保留。Provider 与模型配置均位于用户级 config.toml；字段含义可参阅OpenAI 当前配置参考。

这份单文件配置会默认调用 Astra。部分旧版 Codex 的下拉菜单仍可能不显示它，因为菜单由客户端内置模型目录决定；这不影响按 model = "gpt-6-astra" 进行实际调用。更新 Codex 客户端后再查看菜单。

可选：开启超过 272K 的上下文

需要处理很长的对话或材料时，可为支持长上下文的模型（例如 gpt-5.6-sol 或 gpt-6-astra）提高客户端预算。先退出 Codex 并备份配置文件，然后在 config.toml 的顶层添加或修改下面两行，放在第一个 [... ] 配置块之前，不要放进 [model_providers.codex-stack] 内，也不要重复已有字段：

model_context_window = 1000000
model_auto_compact_token_limit = 900000

第一行将客户端上下文预算设为 1,000,000 Token；第二行在约 900,000 Token 时触发历史自动压缩。它们不会提高模型本身的上限，也不是每次请求必须使用的 Token 数。模型需支持该长度；不要将此配置用于 Spark 等较小窗口模型。若想使用 Sol，将已有顶层 model 改为 "gpt-5.6-sol"，其余接入配置保持原样。

保存后重新打开 Codex Desktop 或 CLI，并新建任务。Windows 原生和 WSL 的配置彼此独立，请修改实际运行环境使用的那份文件。恢复默认预算时，删除这两个自定义字段（若原来已有值，则恢复备份中的值），重开 Codex 并新建任务。字段说明见 OpenAI 配置参考。

费用提醒：开启配置本身不收费；单次请求的实际输入超过 272,000 Token 才触发长上下文加价，恰好 272,000 不触发。 对上述 Astra／5.6 模型，整次请求的普通输入、缓存读取和缓存写入单价乘 2，输出单价乘 1.5，并非只对超出部分加价。门槛按包含缓存的输入总量判断，不按整段对话累计用量判断。以 Sol Standard 为例，输入／输出每百万 Token 从 $4／$20 变为 $8／$30；后续请求若仍携带超过门槛的历史，也会继续按长上下文价格计算。详见价格说明。

Windows 原生

完全退出 Codex 后，在 PowerShell 中打开配置：

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null
notepad "$env:USERPROFILE\.codex\config.toml"

保存上述 TOML 后重新打开 Codex Desktop，或从已设置 API Key 的新 PowerShell 窗口运行 codex。

WSL2

OpenAI 官方 WSL 文档说明，Codex 0.115 起不再支持 WSL1。尚未安装 WSL 时，在管理员 PowerShell 中运行：

wsl --install

进入 WSL 后安装 Codex，并确认运行环境：

echo "$WSL_DISTRO_NAME"
curl -fsSL https://chatgpt.com/codex/install.sh | sh
mkdir -p ~/.codex
nano ~/.codex/config.toml

在 WSL 的配置文件中粘贴同一份 TOML，并在同一个 WSL 终端中设置第 2 节的 CODEX_STACK_API_KEY 后启动 codex。仓库建议放在 ~/code，不要放在 /mnt/c，以避免明显的文件 I/O、权限和符号链接问题。

macOS / Linux

创建 ~/.codex/config.toml，粘贴同一份 TOML，然后在设置过环境变量的同一个终端中启动：

codex

如果 Codex 能正常进入对话并返回回答，即接入完成。出现 401 时检查环境变量；出现连接或 TLS 错误时检查公网连通性和上一节的 NO_PROXY 配置。

切换模型

默认配置已使用 Astra。需要改用 Sol、Terra 或 Luna 时，只修改官方模型名，例如 gpt-5.6-sol、gpt-5.6-terra 或 gpt-5.6-luna。不要添加任何自定义后缀；使用默认 Standard 模式即可。

如果只想验证配置能否被当前 Codex 解析，可先运行 codex debug models --bundled。

5. 接入 DeepSeek Harness（DSH）

DSH 通过 llm-pi-ai 的 OpenAI Completions 适配器接入。API Key 仍从 CODEX_STACK_API_KEY 环境变量读取。Windows 用户配置位于 %USERPROFILE%\.dsh\settings.yaml，macOS、Linux 或 WSL 位于 ~/.dsh/settings.yaml。

DSH 只需配置一个 codex-stack Provider。把以下内容合并进 DSH 用户设置；如果已经有 llm-pi-ai.providers，只加入该 Provider，不要创建第二个 llm-pi-ai：

llm-pi-ai:
  providers:
    codex-stack:
      displayName: Codex Stack
      apiKeyEnv: CODEX_STACK_API_KEY
      baseURL: https://api.meowtis.net/v1
      api: openai-completions
      compat:
        sendSessionAffinityHeaders: true
        sessionAffinityFormat: openai-nosession
      models:
        - id: gpt-5.6-sol
          name: GPT-5.6 Sol
          contextWindow: 262144
          maxTokens: 128000
          input:
            - text
            - image
          reasoningEfforts:
            low: low
            medium: medium
            high: high
            xhigh: xhigh
            max: max
        - id: gpt-5.6-terra
          name: GPT-5.6 Terra
          contextWindow: 262144
          maxTokens: 128000
          input:
            - text
            - image
          reasoningEfforts:
            low: low
            medium: medium
            high: high
            xhigh: xhigh
            max: max
        - id: gpt-5.6-luna
          name: GPT-5.6 Luna
          contextWindow: 262144
          maxTokens: 128000
          input:
            - text
            - image
          reasoningEfforts:
            low: low
            medium: medium
            high: high
            xhigh: xhigh
            max: max

重启 DSH 后选择：

Provider: codex-stack
Model: gpt-5.6-sol

compat 配置会发送稳定的会话亲和请求头，帮助网关把同一 DSH 会话持续调度到同一上游账户。使用默认 Standard 模式，不要新增 Provider、请求头或带后缀的模型名称。

如果 DSH 由桌面图标或后台服务启动，终端中的临时环境变量可能不会传给它。 Windows 可使用第 2 节的用户环境变量；也可以在 DSH 凭据管理界面保存 CODEX_STACK_API_KEY，凭据名称必须与 apiKeyEnv 完全一致。不要把真实 Key 写入 headers 或 settings.yaml。

6. 接入其他 Harness 或 OpenAI 兼容客户端

任何允许自定义 OpenAI Base URL 的客户端都可以使用以下配置：

如果 Harness 只识别标准 OpenAI 环境变量，可在启动它之前设置别名。

macOS / Linux：

export OPENAI_API_KEY="$CODEX_STACK_API_KEY"
export OPENAI_BASE_URL="$CODEX_STACK_BASE_URL"
export OPENAI_MODEL="$CODEX_STACK_MODEL"

Windows PowerShell：

$env:OPENAI_API_KEY = $env:CODEX_STACK_API_KEY
$env:OPENAI_BASE_URL = $env:CODEX_STACK_BASE_URL
$env:OPENAI_MODEL = $env:CODEX_STACK_MODEL

常见的协议名称可能写作：

• openai-responses / responses：使用 POST /v1/responses
• openai-completions / openai-compatible：使用 POST /v1/chat/completions

有些客户端会自动追加 /v1。最终请求地址只能包含一次 /v1，例如 https://api.meowtis.net/v1/models。

所有通用客户端也必须保持官方模型名称，不要添加自定义服务等级请求头或模型后缀。使用默认 Standard 模式，客户端配置保持不变。

7. 直接调用 API

Chat Completions

curl --noproxy "api.meowtis.net" --fail-with-body \
  "$CODEX_STACK_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$CODEX_STACK_MODEL\",
    \"messages\": [
      {\"role\": \"user\", \"content\": \"你好，请回复：连接成功。\"}
    ]
  }"

Responses API

curl --noproxy "api.meowtis.net" --fail-with-body \
  "$CODEX_STACK_BASE_URL/responses" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$CODEX_STACK_MODEL\",
    \"input\": \"你好，请回复：连接成功。\"
  }"

流式 Chat Completions

curl --noproxy "api.meowtis.net" --fail-with-body -N \
  "$CODEX_STACK_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"model\": \"$CODEX_STACK_MODEL\",
    \"stream\": true,
    \"messages\": [
      {\"role\": \"user\", \"content\": \"用三点介绍这个 API。\"}
    ]
  }"

8. Python SDK

python -m pip install openai

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["CODEX_STACK_API_KEY"],
    base_url="https://api.meowtis.net/v1",
)

response = client.responses.create(
    model="gpt-5.6-sol",
    input="你好，请回复：连接成功。",
)

print(response.output_text)

9. Node.js SDK

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.CODEX_STACK_API_KEY,
  baseURL: "https://api.meowtis.net/v1",
});

const response = await client.responses.create({
  model: "gpt-5.6-sol",
  input: "你好，请回复：连接成功。",
});

console.log(response.output_text);

10. 上传并使用附件

单个上传请求上限默认为 25 MiB。文件会保留到客户端显式删除；上传成功后应妥善保存返回的 file_... ID。

上传文件：

curl --noproxy "api.meowtis.net" --fail-with-body \
  "$CODEX_STACK_BASE_URL/files" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY" \
  -F purpose=user_data \
  -F file=@document.pdf

记下响应中的 id，然后在 Responses API 请求中引用它：

{
  "model": "gpt-5.6-sol",
  "input": [{
    "role": "user",
    "content": [
      {"type": "input_file", "file_id": "file_..."},
      {"type": "input_text", "text": "请总结附件。"}
    ]
  }]
}

文件接口还支持：

• GET /v1/files：列出文件
• GET /v1/files/{id}：查看文件信息
• GET /v1/files/{id}/content：下载文件
• DELETE /v1/files/{id}：删除文件

网关按访问账户严格隔离 Files：同一账户的多枚有效 Key 可以访问同一批文件，轮换 Key 不会丢失数据；其他账户查询同一文件 ID 时得到 404。账户身份只由服务端的 Key 注册关系决定，客户端不能用 Header 或请求参数指定。敏感附件用完后仍应调用删除接口。

11. 会话归档与恢复（仅限受信用户）

网关会按会话归档 Chat Completions 和 Responses API 的原始请求与响应。客户端能自定义请求头时，建议每个会话持续发送同一个 X-Session-ID；Codex CLI 等未显式发送该头的客户端，网关会通过 Responses conversation 链或稳定哈希归组。

列出已归档会话：

curl --noproxy "api.meowtis.net" --fail-with-body \
  "$CODEX_STACK_BASE_URL/session-history" \
  -H "Authorization: Bearer $CODEX_STACK_API_KEY"

返回的 archive_id 可继续用于：

• GET /v1/session-history/{archive_id}：查看 turn 列表。
• GET /v1/session-history/{archive_id}/{turn_id}/request：下载原始请求。
• GET /v1/session-history/{archive_id}/{turn_id}/response：下载原始响应；流式调用返回 SSE 原文。

这些接口能恢复对话内容和工具输出，但不会自动把数据重新注册成 Codex Desktop 原生任务；需要时应将导出内容重放到新任务。当前没有面向客户端的会话归档删除接口。

网关按访问账户严格隔离会话归档和 previous_response_id 关联：同一账户下轮换后的 Key 仍能恢复该账户的完整请求与响应，不同账户不能互相列出或读取。公用设备若不应看到主账户历史，应使用独立演示账户，而不是主账户下的临时 Key。

12. 常见问题与错误

为什么长时间 reasoning 会在约 900 秒后返回 500？

这是当前本站接入的 ChatGPT Pro/Codex 订阅服务对单次上游 reasoning 响应的约 900 秒限制，不是本站 8320 网关设置的 15 分钟超时。生产历史与受控重放均显示：请求已经收到 HTTP 200，并持续收到上游事件，但 ChatGPT 上游会在约 901.8 秒时关闭尚未出现 response.completed 的响应流；CLIProxyAPI 随后将这次不完整响应映射为 500。

中途出现文本、reasoning 摘要或工具调用，并不会重置这一个上游响应的 900 秒计时；只有该响应正常完成并由下游发起新一轮请求，才进入新的响应周期。失败流没有最终 usage 事件时，日志中的 token 可能保持为 0；这里的 0 表示“上游未上报/无法确定”，不表示请求没有进行推理，也不能据此判断订阅额度没有消耗。

延长本站代理超时、升级 CLIProxyAPI 或原样重试同一个超长请求都不能消除该限制。下游 Agent 应把长任务设计成可中断、可恢复的多个模型轮次：在 900 秒前设置软截止，将进度、工具结果和下一步写入外部检查点，再用新请求继续；同时拆小单轮目标，并避免对同一超长请求进行无检查点重试。当前架构不能使用 OpenAI Platform Responses API 的 Background mode 绕过此限制，因为本站走的是 ChatGPT 订阅后端，而不是另行计费的 Platform API。

排查时可以记录 HTTP 状态码、请求路径和服务返回的错误消息，但分享日志前必须移除 Authorization 请求头、API Key、上传内容及其他敏感数据。

13. 凭据、安全与服务边界

• 不在源码、Markdown、截图、日志、Issue 或聊天记录中粘贴 API Key。
• 不把 API Key 放进前端网页、浏览器脚本或移动端安装包；应由受控后端代为调用。
• 不同数据边界应使用独立访问账户；同一账户的不同设备使用独立 Key，便于单独过期、轮换和吊销。
• 怀疑 API Key 泄露时，立即在门户删除对应 Key，并联系管理员重新签发；不要只删除出现过密钥的文本。
• 怀疑门户密码泄露时，联系管理员重置；API Key 与门户密码需要分别处置。
• 公共或共享设备使用结束后退出门户，不让浏览器保存登录密码。
• 文档和配置可以分享，但分享前应再次确认其中只有环境变量名，没有凭据值。
• 访问账户负责 Files 与 Session History 的数据归属；API Key 只负责认证，未注册、过期、吊销或账户停用时返回 401。
• 会话归档包含完整请求与响应；同一账户下的所有有效 Key 都能读取该账户归档。
• 本服务使用上游 ChatGPT credits 口径，不是 OpenAI Platform API Token 账单。
• 服务等级在门户或管理后台按 API Key 设置；客户端始终保持官方模型名称。