LinksAPI
免费开始
返回文档首页

AI 编程工具 · OpenAI 官方

Codex CLI 配置教程

OpenAI 官方的终端 AI 编程助手。本教程从安装到第一句对话全程命令对照，重点讲清 config.toml 每一行是什么意思。

预计时间
5-8 分钟
难度
⭐⭐ 入门 +
前置要求
终端基础 · 会编辑文件

📌 30 秒速查（给资深用户）

已经装好 Codex CLI？在 ~/.codex/config.toml 加：

toml
model_provider = "linksapi"
model = "gpt-5.4"

[model_providers.linksapi]
name = "LinksAPI"
base_url = "https://linksapi.cn/v1"
wire_api = "chat"
requires_openai_auth = true

在 ~/.codex/auth.json 加：

json
{ "OPENAI_API_KEY": "sk-你的_LinksAPI_令牌", "auth_mode": "apikey" }

完整教程往下看 ↓

注意：本教程使用 wire_api = "chat"（OpenAI Chat Completions 协议）。 这是所有第三方网关（包括 LinksAPI）通用支持的接口。 官方文档中的 wire_api = "responses" 是 OpenAI 自家的 Responses API，仅 OpenAI 官方 + 少量网关支持， 在中转站走 chat 协议最稳。
1

注册并登录 LinksAPI

打开 api.linksapi.cn， 右上角点「登录」。没有账号就点「注册」，也可以直接用 GitHub / Google 一键登录，免填资料。

看到这个就对了
新注册即送 $0.60 体验额度，足够把本教程整篇跑通，不用先充值。
2

先搞清楚「分组」——90% 的接入失败都卡在这里

LinksAPI 把同一个模型放在不同分组里。分组决定三件事：能调哪些模型、价格倍率、线路来源与稳定性。

不要选 default 分组。default 里只有阿里云的生图 / 生视频模型（qwen-image、wan2.7 等），没有任何 GPT 模型。选它调 Codex，一定报「无可用渠道」。

用 Codex 的话，按下面挑一个：

分组适合
GPT Pro（含codex）0.3倍率首选，站内主推，含 codex-auto-review，性价比最高
GPT低价特供价格最低的一档
GPT 企业级（极速响应）模型最全、响应快，价格高一些
gpt官key 直连来源最干净，模型数量少
codex限时特价福利免费福利线路，可用性不保证，试用可以、生产别用
想先看看各分组都有什么模型、什么价，去模型广场， 左侧可以按分组筛选。建密钥时的下拉框里也会标出每个分组的实时倍率。
3

创建并复制 API 密钥

左侧菜单进「API 密钥」（或直接打开api.linksapi.cn/keys）， 点右上角 「+ 创建 API 密钥」，按下表填：

字段填什么
名称填 codex，方便以后区分不同客户端
分组按上一步选，千万别留 default
额度留空 = 不限，走账户余额
过期时间留空 = 永不过期
模型限制留空，留空才能调该分组下全部模型
IP 白名单留空。家宽 IP 会变，填了容易把自己挡在外面

提交后在列表里点复制图标，拿到 sk- 开头的密钥。

密钥格式是 sk- 加 48 位字符，一共 51 个字符。 通过微信、邮件传这串时很容易被折行截断 —— 这是「401 密钥无效」最常见的原因。 复制后建议数一下长度。
密钥等于你的钱包：不要发到群里，不要提交进 Git 仓库。
4

安装 Codex CLI

OpenAI 提供了一键安装脚本，比 npm 全局安装更稳：

bash
curl -fsSL https://chatgpt.com/codex/install.sh | sh

脚本会自动把 codex 命令装到 ~/.local/bin/ 并加入 PATH。

装好后验证：

bash
codex --version
看到这个就对了
看到版本号就装好了。
command not found: codex
原因： PATH 没刷新
解决： 关闭并重新打开所有终端窗口。还不行就手动 source 一下你的 shell 配置文件（macOS/Linux）。
如果你嫌 curl 一键脚本不放心，也可以从 GitHub Releases 下载对应系统的二进制包手动安装。
5

创建配置目录

Codex 把配置存在用户主目录下的 .codex/ 文件夹。先确保目录存在：

bash
mkdir -p ~/.codex
这一步如果忘了，下一步写配置文件时会报「找不到目录」。先建目录再写文件是个好习惯。
6

写 config.toml（告诉 Codex 怎么连 LinksAPI）

用你喜欢的编辑器打开（不存在会自动创建）：

bash
# 用 nano（最简单）
nano ~/.codex/config.toml

# 或 vim
vim ~/.codex/config.toml

# 或 VSCode
code ~/.codex/config.toml

把下面这段完整复制到文件里：

toml
# 默认走 LinksAPI（下面 [model_providers.linksapi] 块定义）
model_provider = "linksapi"

# 默认模型 - LinksAPI 上稳定的有 gpt-5.4 / claude-sonnet-4-5 等
model = "gpt-5.4"

# 推理强度: minimal | low | medium | high
model_reasoning_effort = "high"

# 不向 OpenAI 上报对话内容（私有数据）
disable_response_storage = true

# === LinksAPI 网关配置 ===
[model_providers.linksapi]
name = "LinksAPI"
base_url = "https://linksapi.cn/v1"
wire_api = "chat"               # OpenAI Chat Completions 协议（通用）
requires_openai_auth = true     # 读 auth.json 里的 key（经网关时的官方写法）
逐行说明 ↑
  • model_provider ← 指定走哪个 provider 配置，名字要跟下面 [model_providers.xxx] 块对应
  • base_url ← LinksAPI 网关地址，带 /v1（OpenAI 兼容协议要带）
  • wire_api = "chat" ← 用通用 Chat Completions 协议，不要写 "responses"（中转站不一定支持）
  • requires_openai_auth = true ← 让 Codex 读 ~/.codex/auth.json 里的 key。不要写 env_key：它读的是系统环境变量而不是 auth.json，写了会报 Missing environment variable
7

写 auth.json（放你的 sk- 令牌）

同样在 ~/.codex/ 目录下创建 auth.json：

json
{
  "OPENAI_API_KEY": "sk-你的_LinksAPI_令牌",
  "auth_mode": "apikey"
}
把 sk-你的_LinksAPI_令牌 整体替换成你刚才复制的完整 sk- 字符串。双引号一定要保留，auth_mode 必须是 "apikey"（小写）。
偷懒办法：登录 LinksAPI 控制台 → API 密钥 → 点令牌行的「使用密钥」绿色按钮 → 选 Codex CLI tab → 自动生成 config.toml 和 auth.json 完整内容，直接复制即可。
8

跑起来！

在任意项目目录下运行：

bash
cd 你的项目目录
codex

首次启动会询问 approval policy（动你文件之前要不要先问你）：

终端 — 你应该看到
Codex CLI — Lightweight coding agent

Choose approval policy:
> 1. on-request   (推荐: 每次都问)
  2. on-failure   (失败时才问)
  3. never        (全自动)

Sandbox mode:
> 1. workspace-write  (只能改当前目录)
  2. read-only        (只能读不能改)
  3. danger-full      (无沙箱，谨慎)

推荐 on-request + workspace-write，最安全又不烦人。

看到这个就对了
看到提示符（一般是空行 + 光标）就连上了。 试发：怎么用 git rebase 合并最近 3 个提交?能收到回复就 OK。
9

日常使用 5 个核心命令

text
# 直接发问
> 解释一下 src/main.rs 这个文件做什么的

# 让 Codex 改代码
> 给 utils.py 加上类型注解

# 跑 shell 命令并让 Codex 看输出
> 跑 cargo test，根据失败修

# 切模型（临时，本次会话有效）
> /model claude-sonnet-4-5

# 查看本次会话消耗
> /cost
Codex 跟 Claude Code 用法很像，但速度更快（gpt-5.4 推理快）、沙箱更细（workspace-write 只能改当前目录）。
10

模型怎么选 / 怎么省钱

Codex 默认走 LinksAPI 后，可用模型不只 OpenAI 一家。在 config.toml 改 model，或会话内 /model 模型名：

模型 ID推理质量售价 输入/输出推荐场景
gpt-5.4 ⭐⚡⚡⭐⭐⭐$1.75 / $14Codex 默认主力
gpt-5.4-mini⚡⚡⚡⭐⭐$0.35 / $2.8快速、便宜，简单任务
claude-sonnet-4-5⚡⚡⭐⭐⭐$4.2 / $21想用 Claude 风格的代码生成
claude-opus-4-6⚡⭐⭐⭐⭐$7 / $35大型重构
11

常见报错速查

401 Unauthorized
原因： auth.json 里的 OPENAI_API_KEY 没写对 / 双引号缺失 / JSON 格式错
解决：
  1. 用 jsonlint.com 验证 auth.json 语法
  2. token 前后不能有空格、必须 sk- 开头
  3. 到 LinksAPI 控制台确认 token 状态「已启用」
Missing environment variable: `OPENAI_API_KEY`
原因： config.toml 里写了 env_key —— 它读系统环境变量，不读 auth.json
解决：
  1. 推荐：删掉 env_key 那一行，换成 requires_openai_auth = true，Codex 就会读 auth.json，配置不用再动
  2. 或者保留 env_key，但必须真的设一个环境变量：Windows 执行 setx OPENAI_API_KEY "sk-你的令牌"，macOS/Linux 执行 export OPENAI_API_KEY="sk-你的令牌"，然后关掉终端重新打开
invalid value 'xhigh' for model_reasoning_effort
原因： legal 值只有 minimal / low / medium / high
解决： 把 model_reasoning_effort 改成 "high" 即可。这是老版本 Codex 文档遗留 bug。
404 / unsupported wire_api
原因： wire_api 写成了 responses 但中转站不支持
解决： 把 wire_api 改成 "chat"（OpenAI Chat Completions 协议，通用）。
503 / 分组下无可用渠道
原因： 令牌所在分组没有对应模型的上游
解决： 切回 default 分组（含 GPT 和 Claude），或把 model 改成你这把令牌能用的模型。
无法找到 ~/.codex/config.toml
原因： 目录不存在
解决： 跑 mkdir -p ~/.codex（Windows: New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex"）。
token 看着对但还是 401
原因： auth_mode 没设成 apikey，Codex 误以为要走 ChatGPT OAuth
解决： 在 auth.json 里加上 "auth_mode": "apikey" 这一行。完整 auth.json 见 Step 5。

配客户端之前，先用这条确认密钥和分组本身是通的：

bash
curl https://linksapi.cn/v1/chat/completions   -H "Authorization: Bearer sk-你的密钥"   -H "Content-Type: application/json"   -d '{"model":"gpt-5.6-sol","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

返回的 JSON 里带 choices 就说明密钥和分组没问题。这条不通，问题就不在客户端配置上，别再折腾配置文件了。

12

进阶：多 profile 切换上游

如果你想在不同项目用不同的模型/key，可以用 profile 机制。在 config.toml 加：

toml
# 默认 profile
model_provider = "linksapi"
model = "gpt-5.4"

# 工作项目 profile：用 Claude
[profiles.work]
model_provider = "linksapi"
model = "claude-sonnet-4-5"

# 私人项目 profile：用最便宜的
[profiles.cheap]
model = "gpt-5.4-mini"

使用：

bash
codex --profile work     # 启用 work profile
codex --profile cheap    # 启用 cheap profile
codex                    # 不带参数 = 默认 profile
长期项目把 profile 名写到项目根的 .codex/config.toml（每个项目自己的覆盖），不用每次手动切。
遇到本文档没覆盖的问题？联系客服微信 宇智波可乐 或 QQ 2981356048， 通常 10 分钟内回复。

还没注册？立即获取 API Key 开始使用

免费注册创建令牌