Codex CLI 实战教程

这是一份完整的 Codex CLI 使用教程：从零安装到实战项目，配合 Picklyone 做成本控制。

如果你只需要最简配置说明，去 Codex CLI 配置；这页是 walkthrough 风格的完整教程。

Codex CLI 是什么

Codex CLI 是 OpenAI 官方的终端编程助手（开源，@openai/codex npm 包），能在你的终端里：

读代码并回答问题：codex "这个函数为什么返回 undefined" — 它会打开文件看完再答
写代码并创建文件：codex "写一个 hello.js 打印当前时间" — 它生成 diff 让你确认后写入磁盘
跑终端命令：codex "把目录里所有 png 压缩到一半大小" — 它生成命令，征求你同意后执行
重构 / 翻译代码：codex "把这个文件从 Python 2 改成 Python 3 并加类型提示"

和 Cursor、Claude Code 相比，Codex 是最纯粹的 CLI Agent：没有 IDE，没有 GUI，一切都在终端里完成。适合 Vim / Neovim 用户、服务器环境、自动化脚本。

准备工作

你需要：

Node.js 18+（node -v 检查）
Picklyone 账号 —— 没有就去免费注册
Picklyone API Key —— 在 API 密钥页 专门为 Codex 建一个

💡 为什么要单独建 Key：Codex 会把 Key 明文写到磁盘 ~/.codex/auth.json。单独 Key + 日限额（例如 $10/天）= 即使这个文件被 git 或 rsync 误传，损失可控、可以直接撤销。

第 1 步：安装

npm install -g @openai/codex
codex --version

看到版本号就说明装好了。

第 2 步：接入 Picklyone

创建目录并写两个文件：

~/.codex/config.toml

model_provider = "OpenAI"
model = "gpt-5.4-mini"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.picklyone.com/v1"
wire_api = "responses"
requires_openai_auth = true

~/.codex/auth.json

{
  "OPENAI_API_KEY": "pk_live_xxxxxxxxxxxxxxxx"
}

Windows 把 ~ 换成 %USERPROFILE%。如果 .codex 目录不存在，先 mkdir -p ~/.codex。

第 3 步：Hello World

打开一个空目录，跑：

mkdir codex-hello && cd codex-hello
codex "写一个 Node.js 程序 hello.js，打印当前时间，不要额外解释"

Codex 会：

先打印它准备做的事（"我要创建 hello.js..."）
展示要写入的文件内容（diff 风格）
问你 "Apply this change? [y/N]"
你按 y → 文件写入磁盘

接着：

node hello.js

应该打印一个时间。恭喜，你的第一个 Codex 任务完成了。

第 4 步：实战——给现有项目改点东西

假设你有个 Python 项目，想让 Codex 给某个函数加上日志：

cd your-project
codex "给 src/api.py 里的 login() 函数加上 info 级日志，记录 email 和 IP"

Codex 会：

自动读 src/api.py
找到 login() 函数
生成 diff
征求你同意后应用

如果不想一步步 approve，可以切自动模式（见下文）。

三种审批模式

Codex 默认最谨慎（怕改坏你代码），但你可以调松：

模式	标志	行为	适合场景
suggest（默认）	`-a suggest`	每个文件改动、每条命令都要你手动 approve	重要生产代码、不熟悉的项目
auto-edit	`-a auto-edit`	文件编辑自动执行，终端命令仍需 approve	日常编码，平衡效率和安全
full-auto	`-a full-auto`	全自动，不问	一次性脚本、沙箱环境、能接受失败的任务

例：

codex -a auto-edit "把整个 src/ 目录里的 console.log 换成 logger.info"

模型选择策略

Codex 默认用 config.toml 里写的模型，也可以命令行临时覆盖：

codex -m gpt-4o-mini "简单的 rename"

推荐策略：

任务	推荐模型	为什么
日常编程	`gpt-5.4-mini` / `gpt-5.4`	快、够聪明、上下文窗口大
简单批改	`gpt-4o-mini`	便宜 10 倍，小任务够用
算法 / 数学	`o1`	推理强但价格翻 10 倍，仅复杂问题
长上下文重构	`gpt-5.4`	128k 窗口稳

Picklyone 专属优化

2.4 折透明价：GPT 系列在 Picklyone 按官方定价 24% 收费，日常 Codex 开销比直连 OpenAI 低一大截。
日限额保底：在 API 密钥页给 Codex 的 Key 设 日限额（daily_limit）。full-auto 模式一旦跑飞，也最多烧到限额就自动停。
模型白名单锁死：同一个 Key 在 允许模型 里只勾 gpt-5.4-mini / gpt-5.4 / gpt-4o-mini，禁用 o1 / o3。Codex 偶尔会推荐 "用 o1 重试" —— 白名单拦下就不会意外扣重的钱。
自动故障切换：Picklyone 内置冗余，某条通道 429 时自动切换，Codex 侧无感知。
每次任务查账：去 API 日志按时间过滤，就能看到整次 Codex 会话的每一轮 token / 成本分布，方便优化 prompt。

常用快捷操作

只让它回答，不让它改文件：codex -q "解释 scripts/build.sh 干了啥"（-q = quiet，read-only）
传入 stdin 的内容作为上下文：cat error.log | codex "这个报错什么原因"
限制工作目录：codex -C path/to/subdir "..."（只读这个子目录的文件）
退出交互 REPL：按两下 Ctrl+C 或输入 /exit

常见坑

"auth.json not found"：~/.codex 目录不存在。先 mkdir -p ~/.codex 再写文件。
401 Invalid API Key：检查 auth.json 的 JSON 字段名是 OPENAI_API_KEY（不是 api_key），值完整以 pk_live_ 开头，两端无空格。
"invalid wire_api"：config.toml 的 wire_api 必须是 "responses"，Picklyone 只支持这个。
命令卡住不动：默认 suggest 模式在等你按 y。要自动化就加 -a full-auto。
auth.json 误 commit 了：马上去 API 密钥页删掉那个 Key 并建新的。Git 历史里的密钥等同于已泄漏，删不干净，直接换 Key 是唯一解。

下一步

想把 Codex 和 Claude Code 的 Provider 配置统一管理？看 CC-Switch。
想在 IDE 里类似地用？看 Cursor 配置或 Cline (VS Code)。
Codex 的每一次调用都记在 API 日志，花的每一毛都看得见。