文档 · 接入指南

Codex CLI 接 TopxAI：下载、安装、配置

2026-09-22

经 GitHub 和 npm 都够不着时也能用的 npm 镜像拿到 Codex CLI，一条命令装好并写入 ~/.codex/config.toml，然后用 gpt-6.1-sol、gpt-6-astra 或 grok-4.7 跑 Codex。

Codex CLI 是 OpenAI 的终端编程代理，走 OpenAI Responses 接口。TopxAI 在 https://ai.topxea.com/v1/responses 为 GPT 系列和 grok-4.7 提供这个接口。这一页从头讲到尾：GitHub 和 npm 下不动时去哪儿拿安装包，哪一条命令能装好并接上 TopxAI，这条命令改了什么，不用脚本时又怎么手动配。

去哪儿拿 Codex

Codex 有三个发布渠道：GitHub Releases（每个系统一个压缩包）、npm（npm install -g @openai/codex）和 Homebrew（brew install codex）。下载页现在提供 TopxAI 桌面应用。GitHub 或 npm 慢或者打不开时，Codex CLI 仍可通过下文的 npm 镜像命令或安装脚本安装。如果从 GitHub 手动选择压缩包，可以这样确认系统：

macOS：苹果菜单，「关于本机」。芯片一栏是 Apple M 系列的，就是 Apple silicon；写着 Intel 的就是 Intel。
Windows：设置，系统，系统信息；「系统类型」写着 x64 或 ARM64。
Linux：uname -m 输出 x86_64 或 aarch64。

包是一个 .tgz，codex 可执行程序在 package/vendor/<目标平台>/bin/ 下，辅助程序放在旁边。解包和 PATH 的事，下面的脚本会替你做；装了 Node.js 的话，npm install -g @openai/codex --registry=https://registry.npmmirror.com 是走镜像的另一条路。

一条命令装好

macOS 和 Linux，在终端里：

curl -fsSL https://ai.topxea.com/install/codex.sh | sh -s -- --key sk-...

Windows，在 PowerShell 里：

$env:TOPXAI_API_KEY = "sk-..."; irm https://ai.topxea.com/install/codex.ps1 | iex

sk-... 换成你在密钥页创建的 TopxAI 密钥，线路选 OpenAI、Grok 或自动路由。不带密钥也行，脚本会隐藏输入向你要，密钥不会留在 shell 历史里。

装完新开一个终端，运行 codex。

脚本改了什么

脚本只动下面这几处，重复运行也没关系：可执行文件换成新的，配置只改它自己写的那几行。

经 npm 镜像下载适合你系统的当前 Codex 包（镜像上你这个系统最新的那个版本），装之前先核对 npm 的完整性校验值。--version 0.155.1 可以指定别的版本。
把包解到 ~/.local/lib/codex，~/.local/bin/codex 链接到里面的可执行程序，再通过 ~/.zshrc 和 ~/.bashrc 里一段带标记的块把这个目录加进 PATH（Windows 上包放在 %LOCALAPPDATA%\Programs\codex，放 codex.exe 的那个文件夹加进用户 PATH）。已经用 npm 或 Homebrew 装过 Codex 的，加 --config-only，只写配置不动程序。
写 ~/.codex/config.toml：model = "gpt-6.1-sol"、model_provider = "topxai"，加一个 [model_providers.topxai] 表。文件里原有的其他内容保留，旧文件存为 config.toml.bak.<时间戳>。
把密钥存进 ~/.codex/topxai.env（权限 0600），由同一段 shell 块导出为 TOPXAI_API_KEY；Windows 上存为用户环境变量。
带着密钥请求 GET /v1/models，告诉你 gpt-6.1-sol 在不在这把密钥的线路上。

其他选项：--model gpt-6-astra 换默认模型，--no-verify 跳过最后那次请求，--base-url 指向自建 relay，--bin-dir 换安装目录。sh -s -- --help 列出全部选项。

手动配置

Codex 已经装好的，配置就是 ~/.codex/config.toml 里的一段供应商设置。必须写在用户级文件里：项目里 .codex/config.toml 中的 model_provider，Codex 不认。

model = "gpt-6.1-sol"
model_provider = "topxai"

[model_providers.topxai]
name = "TopxAI"
base_url = "https://ai.topxea.com/v1"
env_key = "TOPXAI_API_KEY"
wire_api = "responses"

然后导出密钥，启动 Codex：

export TOPXAI_API_KEY=sk-...   # OpenAI、Grok 线路或自动路由的 TopxAI 密钥
codex

wire_api = "responses" 是默认值，也是当前 Codex 版本唯一接受的值，写出来是为了省得猜。base_url 填带 /v1 的地址，Codex 自己拼 /responses。env_key 指定 Codex 从哪个环境变量读密钥，所以启动 Codex 的那个 shell 里得有这个变量：把 export 那行写进 ~/.zshrc 或 ~/.bashrc，Windows 上把 TOPXAI_API_KEY 设成用户环境变量。如果启动 Codex 的程序不继承你的 shell 环境，也可以把密钥直接写进这个表，用 experimental_bearer_token = "sk-..." 代替 env_key。

VS Code 的 Codex 扩展读的是同一个 ~/.codex/config.toml，只要编辑器能看到这个环境变量，供应商设置对它同样生效。

模型

gpt-6.1-sol 和 gpt-6-astra：OpenAI 线路，共享池按牌价 50%，官方线路 90%。
grok-4.7：Responses 接口上唯一的非 OpenAI 模型。
Claude、GLM、Kimi、DeepSeek 和 Jev 在 Codex 里用不了，因为 Codex 只讲 Responses。

换模型用 codex -m gpt-6-astra，或者改 model。推理强度用 model_reasoning_effort 设置。GPT-6.1 Sol 支持 low、medium（默认）、high、xhigh 和 max；模型不能关闭推理，TopxAI 将旧客户端的 none、minimal 转为 low。已保存的模型 ID 请从 gpt-6-sol 改为 gpt-6.1-sol；旧 ID 已退役，不会自动转发。

升级和卸载

再跑一遍安装命令就是升级：它取当前的包，配置和密钥保持不变。要卸载，删掉 ~/.local/bin/codex 和 ~/.local/lib/codex（Windows 删 %LOCALAPPDATA%\Programs\codex 整个目录和它的 PATH 条目）、shell 文件里 # >>> topxai codex >>> 到 # <<< topxai codex <<< 之间的块；连配置和密钥也不要的，再删 ~/.codex。

长上下文

GPT-6.1 Sol 单个请求的输入超过 272K token（含缓存 token）后，整个请求按长上下文单价计费：输入和缓存单价翻倍，输出单价乘以 1.5。GPT-6 Astra 的阈值也是 272K。两档价格见模型页。Codex 会自动压缩长会话。

不通时

刚装完就提示 codex: command not found：shell 还没读到新的 PATH。新开一个终端，或者运行 . ~/.zshrc（或 . ~/.bashrc）。
Codex 提示 TOPXAI_API_KEY 没设置：同一个原因，shell 还没读到新写的那段块；也可能当时跳过了密钥。带上 --key 再跑一遍安装命令。
下载失败或完整性校验值对不上：连接断了。再跑一遍，每次都重新下载。
401：密钥错了，或粘贴时带了空格。402：余额为零。403：这个模型 ID 不在售，或不在这把密钥的线路上。详见常见错误响应。
curl 能通、工具不通：这一页按工具列出常见原因。

模型：grok-4.7, gpt-6.1-sol · 模型与价格