最近后台问得最多的一个问题是Codex 的插件到底怎么选这问题看起来简单其实很容易跑偏。Codex 不是 VS Code也不是浏览器它是在终端里跑的 AI 编程代理能够自己读仓库、改代码、跑测试、提 PR。想让它变得顺手关键不只是装扩展而是把终端、编辑器、规则文件、提示词这些部件组合起来。我折腾了大半年装了卸、卸了装最后留下来 10 个工具到现在没动过。这篇文章就把这份清单完整列出来附带我一直在用的提示词模板给正在配 Codex 环境的朋友一个参考。1. 先搞清楚Codex 的“插件”到底指什么1.1 我理解的四层插件生态一搜“Codex 插件”搜索引擎会给你推什么阿卡丽插件、Figma 汉化插件、DLSS5 插件、豆包去水印插件……看得人脑壳疼。这些和 Codex 编程代理根本不是一回事。我心中的“Codex 插件”是围绕它搭建的一套开发工作流组件按所在层次可以分成四层终端层tmux、zsh 补全、jq、fzf。它们不直接和 Codex 说话但让整个终端环境更适合长时间运行 AI 任务。编辑器层VS Code 官方扩展、远程开发配置。Codex 跑在终端人眼要盯代码编辑器负责呈现 diff。工作流层Git 美化工具、目录管理工具、MCP 服务器。它们把 Codex 的能力延伸到仓库、文件、外部接口。规则层AGENTS.md、提示词片段库。这一层最容易被忽略但恰恰是决定 Codex“懂不懂你”的核心。把这四层想明白你就不会去装一堆花里胡哨的扩展了。真正有用的插件大部分是给终端和工作流“补位”的不是给 Codex 本体重造轮子。1.2 选插件的三个原则第一稳定优先。Codex 的任务经常一跑就是几分钟终端工具如果动不动就卡住、闪退AI 再聪明也白搭。我选工具有个标准纯静态编译的小工具优先需要一堆运行时依赖的往后排。第二权限边界要清楚。Codex 的能力越强它能碰的东西越多。插件若是帮你把权限扩大必须保证随时能收回来。比如 MCP 服务器给了 Codex 文件写入能力我就会限制它只访问当前项目目录而不是整个 home 目录。第三不重复造轮子。Codex 官方已经内置了 diff 查看、仓库搜索、shell 执行能力你再装一个“更聪明的终端”就是重复。插件应该做 Codex 不做的事而不是抢它的活。1.3 我给“不用卸载”定的标准维度要求使用频率每周至少用到 3 次以上学习成本配置一遍后不再需要反复维护故障率装上以后没有主动给我添过乱协作性可以被 Codex 调用也可以被我自己调用满足这四条我才把它写进长期清单。下面要讲的 10 个工具全部经过了这套标准的过滤。2. 10 个我装完就没卸过的工具清单2.1 终端层让 Codex 跑得更舒服tmuxAI 任务的长跑道Codex 处理一个大仓库时经常要做十多分钟甚至更久的连续操作。终端窗口一旦关闭任务就断了写了一半的代码、跑了一半的测试全没着落。tmux 解决的就是这个问题会话独立挂在后台窗口想关就关想回就回。我现在的习惯是先开一个新会话在里面跑 Codextmux new -s codex codex回到任务时再用tmux attach -t codex。如果公司电脑突然要重启tmux 配合tmux-resurrect还能把会话状态捞回来。这个小习惯救过我很多次尤其是 Codex 在跑长测试的时候你不可能一直盯着终端。zsh-autosuggestions 与 zsh-syntax-highlighting命令行手感优化Codex 的命令参数其实不少codex exec、codex chat、codex login加上各种 flags手打容易错。zsh-autosuggestions 会根据历史命令给出灰色补全提示按右键直接接受zsh-syntax-highlighting 会在你输入时把命令、路径、参数用颜色区分开。装好之后最直观的感受是不再频繁往上翻历史命令找例子。我配合 fzf 的CtrlR搜索历史基本能做到“闭着眼睛”把 Codex 常用命令调出来。这类小工具不直接提升 AI 能力但能减少你和终端之间的摩擦力摩擦力小了你才更愿意频繁使用 Codex。jq解析 Codex 输出和日志Codex 在调试模式下会输出 JSON 格式的请求响应日志尤其是配了--debug之后。裸看 JSON 很反人类用 jq 提取关键字段几秒钟完事。codex --debug exec fix the failing test 21 | jq -r .response我还会拿 jq 来验证 MCP 返回的结果、检查 API 响应状态码。很多朋友说 Codex 出问题不知道从哪查起其实第一步就是把日志结构化jq 就是那个把日志变成可读信息的工具。fzf文件、命令、提示词三合一选择器fzf 是个模糊查找器最初我只用它搜文件后来发现它最实用的场景是当“提示词切换器”。我在项目里维护了一个prompts/目录里面放着各种场景的提示词文件然后用 fzf 选择并直接塞给 Codexcodex exec $(cat prompts/$(ls prompts/ | fzf))这个组合拳让我不用记忆一堆提示词片段想起来要做什么直接选文件。fzf 还能搜 Git 提交记录、历史命令属于那种“装了没感觉卸了马上难受”的工具。2.2 编辑器与工作流层把 Codex 接进日常开发VS Code 官方 Codex 扩展很多人问我 Codex 都命令行了为什么还要装 VS Code 扩展。我的答案是命令行负责“跑”编辑器负责“看”。Codex 在终端里改完代码你需要立刻看到改动、跑测试、甚至手动修一下它的大意之处。VS Code 官方扩展可以把 Codex 会话嵌入侧边栏同时在编辑器里直接展示文件 diff。注意一点扩展只是“显示层”实际执行仍然是 Codex CLI 在终端里完成的。所以就算你装了扩展终端的基础环境还是得配好。不要以为装上扩展就能完全替代终端操作。diff-so-fancy 与自定义 Git alias让 AI 的改动一目了然Codex 生成的代码会大量触及 Git 工作区默认的git diff在终端里看多了眼睛疼。diff-so-fancy 把 diff 渲染成更易读的格式行内变化会高亮文件和行号也更明显。我同时在~/.gitconfig里加了几个 alias[alias] d diff --coloralways | diff-so-fancy s status -sb w show --stat --oneline HEAD看 Codex 的改动时先git s看哪些文件被动过再git d看具体内容最后git w确认这次提交的规模。这套流程基本上是我每天和 Codex 协作的固定动作。ripgrep提升 Codex 上下文喂料的效率Codex 虽然能自己搜代码但有时候你需要快速确认某个符号的定义、某个配置项的位置手动用 rg 比等 AI 慢慢翻仓库快得多。更关键的是当我给 Codex 下指令时可以用 rg 先搜出相关文件路径然后把文件路径直接写进提示词告诉 Codex“只看这几个文件”。rg -l class PaymentService src/ | head -20这样 Codex 不用大海捞针我也能确认问题范围的边界。给 AI 提供高质量上下文比给它更聪明的模型更管用。direnv / mise按项目注入环境变量Codex 执行命令时环境变量决定了很多事API Key、模型地址、项目变量。每个项目配一套环境变量如果全靠 shell 手动 export早晚要出事。direnv 可以在你进入项目目录时自动加载.envrc离开目录时自动卸载防止变量串项目。配合 mise 管理运行时版本Node、Python、Go进入目录后版本自动切换Codex 跑测试就不会因为版本不一致产生奇怪问题。这个小环节看着不起眼但很多 CI 里跑得好好的测试在本地被 Codex 跑挂十有八九就是环境变量或运行时版本不对。2.3 配置切换与工具扩展给 Codex 开眼cc-switch多模型/多环境配置切换器Codex 默认连的是官方模型服务但开发者的需求往往更复杂有测试环境、有内网部署的兼容服务、有第三方模型提供方比如 DeepSeek 官方 API。手动改配置文件来切换这些环境很烦还容易改错。cc-switch 是个开源小工具把常用的模型配置存成多套方案点一下就能切换重启 Codex 后生效。我自己的配置里有三套一套官方默认、一套 DeepSeek 官方 API、一套公司内网兼容网关。注意这里说的都是合法合规的业务 API 接入不是让你去碰什么灰色渠道。使用 cc-switch 的要点是给每套配置写清楚备注免得切了三套自己都忘了哪套对应哪个模型。MCP 服务器把外部能力接进 Codex 会话MCPModel Context Protocol是让 Codex 调用外部工具的标准协议。我装了三个一直留着filesystem MCP让 Codex 访问限定的目录、GitHub MCP提 PR、查 issue、Context7 MCP让 Codex 查最新的第三方库文档。装 MCP 的核心原则是最小权限。filesystem 我只允许它读写当前工作区绝不放开整机磁盘GitHub 令牌我配置成只对单个仓库有效。MCP 扩展了 Codex 的能力但也扩大了风险面权限上用小步放行的策略最稳妥。3. 提示词才是真正的“隐藏插件”3.1 为什么提示词比插件更关键插件解决的是“Codex 能碰到什么”提示词解决的是“Codex 该怎么碰”。很多人的 Codex 用起来像无头苍蝇不是因为模型太笨而是因为提示词里全是他自己的心理活动什么“帮我修一下代码”——到底修哪里、用什么标准算修好、输出格式是啥一个字都没写。我把提示词分成两类长驻规则放在 AGENTS.md 里Codex 进仓库时自动读取临时指令放在会话里针对当前任务做具体安排。这两类配合好了Codex 的行为才可预期。下面是我一直在用的模板。3.2 我的 AGENTS.md 模板我的AGENTS.md不长但每一项都指向实际协作中出过的问题# 项目开发规则 ## 角色 你是一个熟悉本仓库的资深工程师擅长写出可维护、可测试的代码。 发现问题时先定位再解释最后动手改。 ## 通用约束 - 不要添加未要求的依赖。 - 不要修改与当前任务无关的文件。 - 提交信息使用 Conventional Commits 风格。 - 修改代码前先检查现有测试新增逻辑必须补测试。 ## 技术栈说明 - 本仓库使用 pnpm 管理依赖。 - 运行测试用 pnpm test不要用 npm test。 - 前端目录在 src/web后端目录在 src/api定位代码时先按目录缩小范围。 ## 禁止事项 - 不要在代码里使用 any 绕过类型检查。 - 不要输出测试生成的临时文件到仓库根目录。 - 不要在没跑通测试的情况下声称“已完成”。AGENTS.md 放仓库根目录即可。Codex 在读取仓库上下文时一般会自动加载这个文件你不需要手动粘贴。但要注意它只是规则文件不是万能药。规则写得太多太散Codex 反而抓不住重点。我一般控制在 30 行以内只保留“错一次就会浪费一小时”的规则。3.3 五条高频提示词片段代码审查请以严格的代码审查者身份检查最近的改动git diff 从 commit 开始。 重点检查错误处理是否完善、边界条件是否覆盖、是否存在性能隐患。 不要修改代码先输出问题清单按严重程度排序每条问题附上代码行号和修改建议。这条提示词的关键是“不要修改代码”。如果不加这句Codex 会在审查时顺手改一堆代码结果你根本不知道哪些是它新改的。测试生成请为 src/utils/date.ts 中的每个函数补单元测试。 要求覆盖正常输入、空输入、异常输入测试用例命名清晰 使用项目已有的测试框架生成后直接运行测试并报告结果。给 Codex 指定“生成后直接运行并报告结果”能有效防止它生成一堆没跑过的测试就完事。重构一段遗留代码src/legacy/parser.ts 中有明显重复逻辑。 请在不改变对外接口的前提下抽出公共函数并保持原有注释。 重构完成后运行相关测试给出改动文件列表。“不改变对外接口”是重构提示词的核心约束。没有这句话Codex 会顺手把函数签名都改了连带改掉所有调用方改动范围瞬间失控。解释遗留代码请阅读 src/legacy/scheduler.js解释这段代码的设计意图、输入输出、以及可能存在的 bug。 输出格式先一句话总结再分点展开最后列出风险点。 不要提出修改方案只需要解释清楚。让 AI 解释而不是改代码是理解老项目最快的方式。加了“不要提出修改方案”之后输出会干净非常多。生成提交信息请根据 git diff 生成 5 条提交信息候选使用 Conventional Commits 风格。 要求每条不超过 50 字说明改动目的而不是罗列文件。Codex 生成提交信息通常很啰嗦限制字数后效果好很多。3.4 提示词工程避坑第一别用“尽量”“可能”这类模糊词。你说“尽量别改无关文件”Codex 就会改几个你不想改的文件因为“尽量”给了它自由裁量权。要说“不要修改无关文件”。第二一次只干一件事。让 Codex 同时“修 bug、写文档、补测试、优化性能”它会手忙脚乱最后每件事都做成半成品。我的习惯是一次会话只给一个任务任务拆小了Codex 的执行质量反而高。第三输出格式必须指定。告诉它“先结论后展开”“用列表输出”“不要贴完整代码只贴关键片段”。AI 的输出格式一旦被约束你阅读和验收的成本会大幅下降。4. 接入 DeepSeek 等第三方模型的配置笔记4.1 Codex 为什么能接其他模型Codex 的定位是 AI 编程代理它的架构设计上把“模型能力”和“代理能力”分开了。代理负责理解仓库、执行命令、管理上下文模型负责生成代码和决策。因此只要模型服务提供符合 OpenAI 接口规范的端点Codex 就有办法通过配置对接。最常见的合法场景是团队内部部署了兼容 gateway或者你申请了 DeepSeek 这类大模型提供方的官方 API。注意无论哪种情况都要走正规渠道合规使用。4.2 实操配置从安装到切换我没有把配置文件手改一遍的习惯而是用变量注入。Codex 类工具普遍支持环境变量覆盖默认端点export OPENAI_BASE_URLhttps://api.deepseek.com export OPENAI_API_KEYsk-你的密钥然后在 config 里指定模型名例如deepseek-chat。更长时间使用的场景我会把配置写进项目目录并让 direnv 在进入目录时自动加载这样不会污染全局环境。如果你用 cc-switch 管理多套配置操作会简单很多新建一套名为deepseek的配置填好模型名和端点地址切换后重启 Codex 即可。我给自己的建议是每套配置都写一两句话备注用途免得时间长了忘了某套配置为什么存在。4.3 处理“model is not supported”一类报错接入第三方模型时最常见的报错就是类似“model is not supported when using codex with a xxx model”。出现这个提示先别怀疑模型服务挂了按下面顺序排查模型名是否写对。第三方模型的命名和官方模型不同去模型提供方的文档页确认准确名称。是否走的是兼容协议。Codex 依赖特定格式的接口能力部分模型提供方只开放了普通聊天接口没有开放 Codex 需要的完整参数这时候需要在前面架一层兼容转换服务不要在 Codex 这边硬配。检查 API 版本字段。有些报错看起来是模型不支持实际是请求体里带了一个对方接口不认识的新增字段降级协议版本或换个端点通常能解决。切回官方端点试一次。如果官方端点一切正常说明问题出在自定义配置上用二分法逐步缩小范围。4.4 一个不算共识的共识别把规则写进聊天框不管是官方模型还是第三方模型我更推荐把长驻规则放进 AGENTS.md。为什么因为会话会清空规则文件不会。每次新开会话Codex 都能自动加载项目规则但聊天里写过的东西翻篇就没了。如果你发现每次都要重复交代“用 pnpm 跑测试”“不要动无关文件”就把这两条写进 AGENTS.md一劳永逸。5. 常见报错与排查技巧实录5.1 cc-switch 切换后报 local 连接失败不少人在用 cc-switch 切换配置后启动 Codex 时看到类似这样的提示切换配置时报 local 连接失败同时伴随codex endpoint /responses的访问异常。第一次遇到很容易慌其实原因基本是一致的cc-switch 保存的某套配置里端点地址指向了一个本地服务比如本地 API 兼容网关但这个服务当前没有启动或者监听端口已经变了。排查步骤先用curl http://127.0.0.1:你的端口号/v1/models确认本地服务是不是活着。如果连接被拒绝去服务日志里找启动失败的原因。打开 cc-switch 的配置项核对 base URL 里写的是不是最新端口。本地服务更新后端口变了是这种问题最常见的原因。如果本地服务不需要了直接切到另一套配置Codex 立即恢复正常。假如你没有单独开本地服务确认是不是环境变量里残留了旧的端点设置用env | grep -i openai查一遍。5.2 登录与鉴权问题codex login卡住、调用时报 401这类问题在换了配置之后很常见。先检查环境变量里是否设置了OPENAI_API_KEY如果设置了Codex 一般会优先读取它而不是你的登录态。此时要么完全依赖 API Key要么清掉环境变量走登录流程两套逻辑混用最容易出问题。如果用了 cc-switch 切换配置切完后建议执行codex login status确认当前身份状态。很多“莫名其妙报错”到最后都是身份状态和配置对不上。5.3 输出乱码与文件权限问题Codex 在中文环境执行命令时偶尔会出现输出乱码。多半是 shell 编码问题把终端编码切到 UTF-8locale也要检查一下。Codex 生成的临时文件偶尔没有执行权限跑测试时报 permission denied这时候不要动不动用 sudo先看是不是生成路径本身不允许执行让 Codex 把临时文件写到项目下的.tmp目录再逐个排查。调用 MCP 文件写权限出问题也很常见你给了权限但终端会话的工作目录不是项目目录导致写操作失败。处理方式是路径保持绝对路径并且在 MCP 配置里明确允许的根目录。5.4 问题排查速查表症状可能原因处理方式切换配置后 local 连接失败本地兼容服务未启动或端口不一致检查服务状态核对 base URL请求返回 401API Key 失效或登录态冲突更新 Key或清理环境变量后重新登录model is not supported模型名写错、协议不兼容对照文档改模型名必要时加转换层命令执行权限不足临时文件路径不可执行让 Codex 把临时文件写到项目目录中文输出乱码终端编码不是 UTF-8切换终端编码检查 localeCodex 不读 AGENTS.md文件不在仓库根目录或名字不对确认文件名和位置重新打开会话写在最后的个人体会我自己用下来的真实体会是工具会换提示词库会越来越厚真正让 Codex 变得“懂你”的其实是那几页规则文件。插件能解决“它能干什么”但只有提示词和规则能解决“它干得怎么样”。每次遇到 Codex 因为缺少上下文而做蠢事我都会提醒自己它不是故意犯蠢是我没把边界说清楚。最后再分享一个小技巧我在每个项目里都会放一个COOKBOOK.md专门记录这个项目里 Codex 常踩的坑、必须遵守的规范、以及它之前犯过的蠢错误。每遇到一次就追加一条。几个月下来这个文件比任何插件都好用因为它是你亲手调教出来的“项目大脑”。工具是死的上下文是活的。这大概就是我装完那 10 个工具就再也没卸过的真正原因。