OpenAI Codex CLI及插件配置指南与调教心得

背景

随着大语言模型在代码生成与辅助开发领域的深入应用，开发者对 AI 编程助手的依赖日益加深。此前，许多开发者倾向于使用基于 Claude 模型的 Claude Code (CC) 进行本地代码交互，但高昂的 API 中转成本及潜在的访问限制促使部分技术社区成员寻找替代方案。OpenAI 推出的 Codex CLI 工具及其配套的 VS Code/Cursor 插件，因其对 gpt-5 系列模型的支持以及更灵活的配置选项，逐渐成为高强度代码开发者的新宠。

本文档基于 LINUX DO 社区的技术分享，详细记录了从 Codex 的安装、基础配置、插件适配到高级调优（如 AGENTS.md 全局指令设定）的全过程。特别是针对 2025 年 9 月期间发布的 gpt-5-codex 新模型及插件版本变动（0.5.9/0.5.10），提供了具体的避坑指南与配置修正，旨在帮助开发者将 Codex 打造为高效、可控且“听话”的编程伙伴。

核心内容

1. Codex 安装与基础环境配置

安装方式 通过 npm 全局安装 Codex CLI 工具：

npm i -g @openai/codex

配置文件结构 Codex 的核心配置位于用户目录下的 ~/.codex/config.toml。若文件不存在需手动创建。主要配置项包括：

• 模型选择 (model)：支持 gpt-5 以及新版 gpt-5-codex。
• 推理强度 (model_reasoning_effort)：可选 high, medium, low，用于控制模型的思考深度。
• 网络与存储：建议启用 network_access 以允许联网搜索，设置 disable_response_storage = true 以保护隐私。
• 模型提供商 (model_provider)：支持自定义中转站。示例中配置了 packycode 和 duck 两个提供商，分别对应不同的 base_url 和 wire_api 接口类型（responses 或 chat）。

环境变量配置 API Key 不应直接硬编码在配置文件中，而应通过环境变量管理。在 ~/.zshrc 中导出 Key：

export packycode_codex_key="sk-xxx"
export instcopilot_codex_key="sk-xxx"

随后执行 source ~/.zshrc 生效。

CLI 指定模型 在终端中可通过 -m 参数指定使用的模型：

codex -m gpt-5
codex -m gpt-5-codex

2. VS Code / Cursor 插件配置与版本陷阱

插件安装 在 VS Code 或 Cursor 的市场中搜索并安装 Codex 插件。

版本警告 2025 年 9 月 16 日更新的插件版本 0.5.9 和 0.5.10 进行了重大调整，导致旧配置失效。若遇到兼容性问题，建议回退至 0.5.8 或更早版本。

Setting.json 配置 在插件设置中，需配置中转站 URL 及模型参数。注意：新版插件（0.4.9+）中部分旧配置项已废弃，但仍需确保以下核心项正确：

"chatgpt.apiBase": "https://codex-api.packycode.com/v1",
"chatgpt.config": {
    "preferred_auth_method": "apikey",
    "model": "gpt-5", // 或 gpt-5-codex
    "model_reasoning_effort": "high",
    "disable_response_storage": true,
    "wire_api": "responses"
}

Auth 配置 插件需通过 ~/.codex/auth.json 读取 API Key，格式如下：

{
  "OPENAI_API_KEY": "sk-xxx"
}

3. 交互模式差异：@ 符号的使用

Codex 与 Claude Code 在文件引用逻辑上存在显著差异，开发者需特别注意：

• CLI 中的 @ 符号：
  • 输入 @ 后，Codex 进入文件索引/搜索模式，而非直接列出当前目录文件。
  • 用户需输入文件名或目录关键字进行搜索。
  • 图片引用：CLI 中 @ 仅支持引用本地文件，不支持直接从剪贴板粘贴图片（这与 Claude Code 不同）。
• 插件中的引用：
  • 逻辑与 CLI 一致，操作相对简便，支持文件引用。

4. 高级调教：AGENTS.md 全局指令

为了实现“授人以渔”的交互体验，Codex 支持通过 ~/.codex/AGENTS.md 定义全局系统提示词。该文件指导 Codex 在代码库中的行为模式。

角色定位

• 资深全栈专家 & 架构师：具备宏观架构设计能力。
• 技术导师：不仅提供代码，更解释思路、原理及最佳实践。
• 技术伙伴：协作解决问题，而非单纯执行命令。

思维模式

• 系统性分析：从整体到局部，评估可扩展性与风险。
• 多角度推理：结合技术、业务、运维视角。
• 中文优先：强制使用中文进行思考、注释及文档生成。

MCP (Model Context Protocol) 规则 文档详细定义了四种 MCP 工具的使用规范：

1. Sequential Thinking：用于复杂问题分解，限制步骤数（6-10步），输出可执行计划。
2. DuckDuckGo：用于最新信息检索，限制结果数量（≤35条），强调来源权威性，设置超时与退避策略。
3. Context7：用于技术文档聚合，优先解析库 ID，精炼输出关键片段，避免大段复制。
4. Serena：用于代码语义检索与符号级编辑，辅助大型代码库的重构与定位。

交互原则

• 授人以渔：提供多方案对比、成本评估及原理深度解析。
• 互动式交流：通过提问引导用户思考，验证思路，提供代码审查建议。
• 安全合规：默认离线优先，外呼需遵守隐私与 ToS，敏感信息不上传。

关键要点

• 模型与提供商灵活性：Codex 支持通过 config.toml 灵活切换不同的中转站提供商（如 packycode, duck），并支持 gpt-5 及新发布的 gpt-5-codex 模型，推理强度可配置。
• 插件版本兼容性风险：2025 年 9 月中旬发布的 Codex 插件版本（0.5.9/0.5.10）存在重大变更，旧配置可能失效。若遇到异常，建议降级至 0.5.8 版本或查阅最新问题汇总。
• 文件引用逻辑差异：在 CLI 中使用 @ 是触发搜索索引，而非列出文件；且 CLI 不支持剪贴板图片粘贴，仅支持本地文件引用。这与 Claude Code 的行为不同。
• 环境变量管理：API Key 应通过 ~/.zshrc 等环境变量管理，并在 ~/.codex/auth.json 中映射给插件使用，避免硬编码。
• AGENTS.md 的核心价值：通过全局指令文件，将 Codex 从“代码生成器”转变为“技术导师”。强制中文输出、多方案对比、MCP 工具调用规范（如 DuckDuckGo 的限流与降级策略），