本文是一份 Codex CLI 的深度实践指南，不仅涵盖了基础的安装配置，更深入解析了多 Provider 切换、认证机制及本地历史记录的边界，旨在帮助开发者高效、安全地驾驭这款强大的本地 AI 编程工具。
智能速览
Codex CLI 支持通过 brew、npm 或官方脚本在 macOS 与 Linux 上安装。
用户可在配置文件 `config.toml` 中设置并切换多个 AI 服务 Provider。
认证方式更推荐使用环境变量，便于安全管理和持久化配置。
即便关闭历史记录持久化，会话恢复文件仍会本地保存，无法真正无痕。
理解配置、认证与记录机制，是平衡工具效率与个人隐私的关键。
精华内容
掌握 Codex CLI 不仅仅是安装运行，更在于理解其配置体系与行为逻辑，从而实现高效与隐私的平衡。
安装与验证
Codex CLI 提供了多种安装途径以适配不同操作系统。在 macOS 环境下，最便捷的方式是通过 Homebrew：`brew install codex`。对于 Linux 用户，则可以采用官方提供的安装脚本：`curl -fsSL https://developers.openai.com/codex/install.sh | sh`。此外，无论在哪个系统，只要安装了 Node.js 和 npm，都可以通过全局安装命令 `npm i -g @openai/codex` 来完成部署。安装完成后，通过在终端执行 `codex --version` 命令，若能正确显示版本号，即代表安装成功，工具已准备就绪。
配置核心解析
Codex CLI 的所有本地配置都集中在用户主目录下的 `.codex` 隐藏文件夹中。这个文件夹包含了四个核心文件：`config.toml`、`auth.json`、`history.jsonl` 和 `sessions` 目录。其中，`config.toml` 是主配置文件，用户可以在此定义多个 AI 服务 Provider，并通过 `model_provider` 字段指定当前默认使用的服务。这种设计使得在不同模型或服务间切换变得非常简单和结构化。
Provider 切换技巧
切换 AI 服务 Provider 有两种主要方式。一种是直接编辑 `~/.codex/config.toml` 文件，修改 `model_provider` 的值后永久生效。另一种是临时性的，通过命令行参数 `codex --config model_provider=“provider_a”` 来指定，这种方式仅在当前命令实例中有效，不影响全局配置。这种灵活性允许开发者针对不同任务快速切换到最合适的 AI 模型，而无需反复修改配置文件。
认证与环境变量
在认证管理上，Codex CLI 支持将 API Key 存入 `auth.json` 文件，但更推荐的做法是使用环境变量。通过 `export PROVIDER_A_KEY=“xxxxxx”` 命令设定 Key，并将其写入 shell 配置文件（如 `~/.zshrc` 或 `~/.bashrc`），即可实现持久化。这种方法不仅安全性更高，避免了密钥明文存储，也更便于在不同 Provider 间切换和管理，可以配合 alias 命令进一步简化操作流程。
历史记录的边界
虽然 Codex CLI 提供了 `history.persistence` 配置项来控制是否将会话内容写入 `history.jsonl` 文件，但请注意，这并不意味着可以实现完全的无痕使用。即便将此项设为 `false`，工具仍然会在 `sessions` 目录中创建文件，用于会话恢复和执行回放。因此，从隐私角度看，Codex CLI 并非一个完全无痕的工具，所有交互记录最终都会在本地留下痕迹，这是其工程化设计的一部分。
Codex CLI 是一个工程化程度很高的本地 AI 编程工具，理解其配置和记录机制是高效使用的前提。在享受 AI 辅助编程带来便利的同时，也需正视其本地记录的现实，做出符合个人需求的平衡选择。
