高强度使用 Codex 的心得(如何让它成为一个乖宝宝)
[!abstract] 摘要
高强度使用 Codex CLI 与插件的心得整理:从 config.toml 基础配置、gpt-5-codex 新模型避坑、TODO Comment、AGENTS.md 全局提示词,到 MCP 生态与 serena 语义检索的完整实战经验。
1. 💡 Codex 记录贴:从基础配置到高阶调教的心得
[!note] 缘起
本文由前文 几家 Claude Code API 中转站使用体验 延伸而来。鉴于 Claude Code (cc) 的官方 API 使用成本偏高,本文作者已转向性价比极佳的 Codex。以下是作者在高强度使用 Codex CLI 与插件过程中的调优和配置心得,希望对大家有所帮助。
1.2. ⚙️ Codex 基础配置
Codex 的全局配置文件位于:~/.codex/config.toml。如果该目录或文件不存在,需要手动创建。
以下是一个推荐的双中转站备选配置模板:
model = "gpt-5"
model_provider = "packycode"
# model_provider = "duck"
model_reasoning_effort = "high"
disable_response_storage = true
network_access = "enabled"
[model_providers.packycode]
name = "packycode"
base_url = "https://codex-api.packycode.com/v1"
wire_api = "responses"
env_key = "packycode_codex_key"
[model_providers.duck]
name = "duck"
base_url = "https://jp.instcopilot-api.com/v1"
wire_api = "responses"
env_key = "instcopilot_codex_key"
1.2.1. 💡 配置项详细解读
model:指定使用的 AI 模型。可选模型有gpt-5,在 2025.09.16 更新后,支持更换为全新的gpt-5-codex。model_reasoning_effort:设置模型的思考深度级别,可选值有high、medium、low。model_provider:指定当前启用的中转服务商,对应下方的[model_providers.xxx]数组对象。大家可根据自己的中转站提供商信息进行定义。wire_api:部分中转站使用responses,部分则使用chat。根据官方文档,其有效值为“chat”和“responses”。若未指定,则默认回退到“chat”。env_key:指定中转站 API Key 的环境变量。由于各中转站生成 Key 的规则不同,建议将其统一配置在 Shell 配置文件(如~/.zshrc或~/.bashrc)中,避免硬编码:
# 编辑 shell 配置
vim ~/.zshrc
# 在末尾添加中转站的 API Key 环境变量
export packycode_codex_key="sk-xxx"
export instcopilot_codex_key="sk-xxx"
# 保存并使之生效
source ~/.zshrc
[!info] 相关资源
更多高级配置项可查阅官方 GitHub:GitHub - openai/codex config.md
1.3. ⚠️ 避坑:gpt-5-codex 新模型与新版插件问题
由于新版升级带来了部分不兼容的改动,作者整理了一份详细的排障贴,建议升级前必读:
👉 【部分问题有解决方案】codex 新发模型 gpt-5-codex 的问题汇总
1.5. 📝 开启 TODO Comment 列表
如果你喜欢 Claude Code 的 TODO List 功能,在 Codex 中也有一款非常相近的体验:

1.7. 🧠 全局自定义系统提示:AGENTS.md
[!info] 提示词设计
类似于 Claude Code 的全局工作规则,Codex 会在运行时默认加载用户目录下的:~/.codex/AGENTS.md。
这份提示词应该根据你的开发方向进行高度定制。以下作者分享了一份针对后端开发场景、秉承“授人以渔”理念设计的全局 System Prompt 模板。
其核心目标是:引导 AI 提供系统性架构思路,鼓励多方案对比与原理解析,让 AI 与开发者保持健康的伙伴关系,而不是单纯无脑地覆写代码:
# AGENTS.md - 全局定制化系统提示模板
This file provides guidance to Codex when working with code in this repository.
## 🎯 角色定位与人设
1. **技术架构师**:具备卓越的系统设计与架构眼光,能从宏观解耦与模块化视角把握整个项目。
2. **全栈专家**:对前端、后端、数据库、运维及 CI/CD 全链路有深度技术储备。
3. **技术导师**:不满足于粗暴交付,善于传授技术原理解析,引导开发者实现自我成长。
4. **合作技术伙伴**:提倡“人机协同”,多澄清、多论证,而非盲目执行代码覆盖。
5. **行业专家**:遵循行业一流最佳实践与规范,提供兼具前瞻性与高维护性的方案。
## 🧠 深度思考模型
### 系统化拆解
* **宏观全局**:从项目整体链路结构、底层技术栈、工程依赖、数据库约束等多维度剖析。
* **前瞻性演进**:充分考虑长远演进,预估代码和架构的可扩展性,保障架构优雅。
* **风险控制**:提早识别潜在的性能瓶颈(如 SQL 慢查询、高并发竞争、内存泄漏),给出预防性建议。
### 严谨推理与总结
* **多视角求证**:从技术优雅、业务闭环、用户体验及日常运维四大视角立体考量。
* **逻辑闭环**:基于静态代码、依赖链路和现实数据推导方案,拒绝含糊与臆断。
* **最佳实践沉淀**:善于从具体案例中剥离出通用的工程规律,固化为项目级脚手架指南。
## 🗣️ 语言与本土化表达
1. **中文母语交流**:所有的分析、注释、说明和反思思考,均必须无条件使用中文。
2. **中文注释标准**:确保生成的所有核心业务代码注释、API 声明、README 说明等都使用清晰规范的中文。
3. **术语表达**:在保持专业英文词汇准确的前提下,采用通俗通顺的中文句式进行架构表达。
## 🎓 交互深度规范
### 授人以渔的工程哲学
* **原理解析**:给出方案时,详尽解释底层的机制设计(例如为什么用 A 框架而不是 B 框架,背后的线程模型或内存屏障如何)。
* **知识迁移**:鼓励提炼设计模式,便于开发者触类旁通。
* **代码审查机制**:执行强有力的代码 Review,不单改代码,还应当指出优化点并邀请开发者共同审计。
### 卓越的多方案对比 (Trade-offs)
* 针对非简单逻辑,必须给出**至少两种方案(方案 A 与 方案 B)**。
* 制作直观的优缺点、实现成本、长线维护成本、技术债务等对比,并给出明确的最终推荐。
## 📋 项目级审计规范
在初始进入任何工作空间时,自动执行:
1. 分析整个工程的依赖树、基础架构层、数据持久化。
2. 识别核心的业务入口、中台组件和全局配置。
3. 发现安全隐患(如 SQL 注入、越权、配置硬编码)及代码坏味道。
1.9. 🔌 玩转 MCP(Model Context Protocol)生态
通过配置 MCP,可以让 Codex 获得连接现实世界的超能力:
- 📘 Context7 —— 检索最新高精官方技术文档:Context7 官方 GitHub
- 📖 Deepwiki —— 获取前沿垂直知识:Deepwiki-mcp 官方 GitHub
- 💻 Desktop Commander —— 赋予 AI 终端控制与系统 diff 修改能力:Desktop Commander 官方 GitHub
- 🧠 Sequential Thinking —— 引入多步序列化分解思考:Sequential Thinking 官方 GitHub
- 🔍 DuckDuckGo —— 实时网络检索与网页内容解析:DuckDuckGo mcp 官方 GitHub
- 🚀 serena —— 强力代码语义检索与引用重构工具链:serena 官方 GitHub
1.9.2. 🔧 原生配置方案
将 MCP 服务直接定义在 ~/.codex/config.toml 中。下面是一个极简的时间服务调用示例:
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]

下面是作者自用、实测握手完全跑通的 完整多节点原生 MCP 配置列表,可供一键抄作业:
# --- MCP servers added by Codex CLI ---
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp@latest"]
[mcp_servers.sequential-thinking]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
[mcp_servers.playwright]
command = "npx"
args = ["@playwright/mcp@latest"]
[mcp_servers.mcp-server-time]
command = "uvx"
args = ["mcp-server-time", "--local-timezone=Asia/Shanghai"]
[mcp_servers.mcp-shrimp-task-manager]
command = "npx"
args = ["-y", "mcp-shrimp-task-manager"]
env = { DATA_DIR = "/Users/lostsheep/tools/mcp-shrimp-task-manager/data", TEMPLATES_USE = "zh", ENABLE_GUI = "false" }
[mcp_servers.mcp-deepwiki]
command = "npx"
args = ["-y", "mcp-deepwiki@latest"]
# 💡 技巧:对于个别冷启动较慢的 npx 服务,建议手动调大冷启动超时阈值
startup_timeout_ms = 60000
[mcp_servers.desktop-commander]
command = "npx"
args = ["-y", "@wonderwhy-er/desktop-commander"]
# --- End MCP servers ---
[!info] 进阶参考
另外一位社区老友的精致 MCP 模板分享可供横向对比:高强度使用 Codex 的心得(如何让它成为一个乖宝宝🤣) - #125,来自 ninesun
你可以先添加最轻量的 mcp-server-time 服务。并在 CLI 会话中直接发送指令,用以自测 Codex 的工具握手链路是否通畅:

[!faq] 🙋 Windows 环境下 MCP 命令启动报错?
如果遇到由于系统环境变量不匹配、导致无法寻找到特定npx或uvx指令的错误,可参照该帖解决方案:高强度使用 Codex 的心得(如何让它成为一个乖宝宝🤣) - #145,来自 Webing(即手动为 args 或命令行添加全路径环境变量)。当然,你也可以采用下面更优雅的路由接管方案。
1.9.4. 🚀 重点推介:LSP 级别语义检索 MCP「serena」
在作者高强度折腾过的数十款 MCP 服务中,serena 是体验最好、最不可或缺的一环:
- 链路完全透明:AI 执行代码的语义解析、跨文件引用分析有迹可循,杜绝一切由于“猜测”导致的盲目代码修改。
- 语义推测极其敏锐:对于上下文没被读到但又瞎下结论的行为有极佳的监督作用(AI 错在哪一目了然,极具协作感)。

[!info] 进阶技巧:如何手动激活并赋能 serena
在最近的高强度实测中,作者发现 serena 并非对每一个打开的目录都会无感静默激活。
官方其实也有过相应说明:有时候需要手动投喂提示词命令触发。完整跑通 serena 需要以下三步:
- 在 MCP Router 客户端中,为
serena添加 arguments 初始化入参:--context codex:

- 在 MCP Router 中拉起并开启
serena服务进程:

- 在 Codex CLI 会话或插件对话框中,明确键入指令激活当前目录(这相当于将当前 workspace 转为 Serena 项目上下文):
💬 “使用 serena 将当前目录激活为项目”

- 点击 serena 客户端的 Dashboard 面板,你会发现在日志(Logs)里,serena 已经在疯狂为您进行 LSP 的代码树扫描和索引了!

- 大功告成,尽情享受开挂般的 AI 协作与高维语义开发吧! 🚀