使用 Codex CLI 的完整实践记录：安装、配置、Provider 切换、认证、历史记录与“无痕”使用的现实边界

本文记录我在本地使用 OpenAI Codex CLI 过程中的完整实践：
包括安装方式、配置结构、多 Provider 切换、认证机制、环境变量持久化、本地历史记录控制，以及“无痕使用”的现实边界。

---

一、Codex CLI 是什么？

Codex CLI 是一个 工程型的本地 AI 编程工具。
它并不是传统意义上的“聊天程序”，而是一个：

• 具备 项目上下文（Workspace）
• 支持 多 Provider / 中转
• 具备 可恢复会话（resume）
• 会在本地生成执行与会话记录

它更像一个本地编程助手 / Agent Runtime，适合用来：

• 做工程级代码生成与修改
• 作为本地 coding assistant
• 在不同模型提供方之间灵活切换

---

二、Codex CLI 的安装方式（多种）

方式一：macOS（推荐）

brew install codex

---

方式二：Linux（官方脚本）

curl -fsSL https://developers.openai.com/codex/install.sh | sh

---

方式三：使用 npm 安装（跨平台）

npm i -g @openai/codex

说明：

• 该方式依赖 Node.js
• 与系统包管理（brew / 官方脚本）相比隔离性略弱
• 但在 CI、容器或 Node 环境中非常方便

---

安装完成后验证

codex --version

---

三、Codex 的本地配置目录结构

Codex 使用固定的本地配置目录：

~/.codex/
├── config.toml      # 核心配置
├── auth.json        # API Key（仅 OpenAI-style Provider 使用）
├── history.jsonl    # 历史记录文件
└── sessions/        # 会话与执行记录（rollout）

---

四、config.toml 的基础结构（多 Provider）

下面是一个通用、可切换、已脱敏的配置示例：

# 当前使用的 provider
model_provider = "provider_a"
model = "gpt-x.y"
model_reasoning_effort = "high"

# ===== Provider A（环境变量 Key）=====
[model_providers.provider_a]
name = "provider_a"
base_url = "https://api.example-a.com/openai"
wire_api = "responses"
requires_openai_auth = true
env_key = "PROVIDER_A_KEY"

# ===== Provider B（auth.json Key）=====
[model_providers.provider_b]
name = "provider_b"
base_url = "https://api.example-b.com/v1"
wire_api = "responses"
requires_openai_auth = true

---

五、Provider 的切换方式（两种）

方式一：修改配置文件

model_provider = "provider_a"

改为：

model_provider = "provider_b"

保存后重新启动 Codex。

---

方式二：使用命令行临时切换（推荐）

codex --config model_provider="provider_a"

或：

codex --config model_provider="provider_b"

特点：

• 不修改 config.toml
• 只对当前启动实例生效
• 非常适合临时测试或快速切换

---

六、认证机制说明（避免混乱的关键）

1️⃣ auth.json 的作用范围

{
  "OPENAI_API_KEY": "sk-xxxx"
}

说明：

• 仅在 Provider 未配置 env_key 时使用
• 是否设置为 null，不会影响使用 env_key 的 Provider

---

2️⃣ 使用环境变量的 Provider（推荐）

env_key = "PROVIDER_A_KEY"

临时设置方式：

export PROVIDER_A_KEY="xxxxxx"

优点：

• 不写入明文配置文件
• 更安全
• 更适合多 Provider / 中转场景

---

3️⃣ preferred_auth_method 的实际意义

preferred_auth_method = "apikey"

这是一个认证优先级提示项：

• 用于在存在多种认证来源时指定偏好
• 不会强制触发某种登录流程
• 在 CLI 场景中不影响 API Key 的正常使用

---

七、将环境变量持久化写入终端配置文件

前面的 export 方式只在当前终端会话中有效。
如果希望每次打开终端都自动生效，需要将环境变量写入终端配置文件。

---

macOS（zsh）

配置文件：

~/.zshrc

加入：

export PROVIDER_A_KEY="xxxxxx"

生效：

source ~/.zshrc

---

Linux（bash）

配置文件：

~/.bashrc

加入：

export PROVIDER_A_KEY="xxxxxx"

生效：

source ~/.bashrc

---

验证是否成功

echo $PROVIDER_A_KEY

---

推荐与 alias 一起维护

export PROVIDER_A_KEY="xxxxxx"

alias codex-a='codex --config model_provider="provider_a"'
alias codex-b='codex --config model_provider="provider_b"'

---

八、历史记录保存策略（官方可配置部分）

Codex 提供了明确的历史记录控制项，用于决定是否将会话写入本地历史文件。

在 config.toml 中可以这样配置：

# 保存历史
history.persistence = "save-all"

# 不保存历史
# history.persistence = "none"

说明：

• save-all：将会话写入 history.jsonl
• none：不将会话写入 history.jsonl

这是官方提供、可配置的历史控制机制。

---

九、关于本地记录的真实情况

在实际使用中，Codex 本地会生成多种记录文件：

• history.jsonl
• sessions/rollout-*.jsonl

实践结论：

• 本地记录并非单一“聊天记录”

• 有些记录用于：

  • 会话恢复
  • 执行回放
  • 工具调用审计

即使关闭历史保存配置，仍然会存在部分会话与执行记录。因此：

目前无法做到真正意义上的“完全无痕”本地使用

---

十、隐私与使用建议（工程实践）

如果你在意他人看到本地历史内容，可以考虑：

1. 使用独立的系统用户账户
2. 使用完成后清理本地记录目录
3. 在不同使用场景下采用不同配置或启动方式

这些方式可以显著降低历史内容的可见性风险。

---

十一、Linux / macOS 的终端配置文件速查

系统	常见 shell	配置文件
macOS	zsh	~/.zshrc
Linux	bash	~/.bashrc

---

十二、总结

• Codex CLI 是一个 工程型本地工具
• Provider、认证、环境变量、历史记录之间存在清晰但不直观的边界
• 本地记录的存在是设计的一部分，而非配置失效
• 理解这些机制后，才能合理选择使用方式