给 Codex CLI 装上 shell 补全：一份不靠猜的落地清单

2026-08-09

天天敲 Codex（OpenAI Codex）的命令行版本，最烦的就是子命令记不全。exec 还是 e，resume 后面跟不跟 --last，-s 的三个取值到底哪个拼法对——每次犹豫一下，就得停下来翻一遍 --help。shell 补全就是干这个的：敲一半按 Tab，剩下的让 shell 补。

Codex CLI 自带了这个能力。在 codex-cli 0.147.0（Windows 11）上执行 codex --help，子命令表里有这么一行：

子命令	官方说明
`completion`	Generate shell completion scripts

一句话，没了。这篇文章要解决的问题就是：只有这一句的情况下，怎么把补全稳稳装上，并且知道它什么时候会失效。

先把话说在前面：我这次的采集只跑了只读命令，codex completion 这个子命令本身的参数表（支持哪几种 shell、取值怎么拼）我没有逐字记录，所以下面不会给你一串”照抄就行”的固定命令。这不是偷懒——恰恰相反，抄一串来路不明的命令是这件事上最常见的失败方式，原因下一节就说。

第零步：先确认你现在用的是哪个 codex

装补全之前先做这一步，能省掉后面一半的排查时间。

codex --version
codex doctor --summary

为什么这两条要一起跑：

codex --version 给你当次的版本号。在 codex-cli 上这个数字是会自己变的——本机采集时开头执行得到 codex-cli 0.131.0，十几分钟后再执行同一条命令，输出变成了 codex-cli 0.147.0，而 which -a codex 全程只有一个可执行文件。所以”我记得我装的是某某版本”这种说法在这里没有意义，一切以当次输出为准。
codex doctor --summary 的 Environment 分组里有 runtime 和 install 两行。在 codex-cli 0.147.0（Windows 11）上，runtime 行会写明这个 codex 是从哪种渠道装的、可执行文件落在哪几个路径（本机是 npm，行里带 package、bin、resources、path 四个路径），install 行给的是 consistent 这类一致性判断。装过好几遍、不确定当前 PATH 上跑的是哪个的，看这两行比自己翻环境变量快得多。

补全脚本是绑在”某个具体的 codex 可执行文件”上的。如果你机器上有两份 codex，而补全脚本是照着另一份生成的，后面所有现象都会很诡异。

第一步：取本机版本的真实参数，别抄别人的

codex completion --help

就这一条。先看它的 --help 输出再动手，本篇不预设它接受什么参数、支持哪些 shell 的取值拼法——那是你本机这个版本说了算的事。

为什么必须自查而不是抄现成命令？两个理由：

一是版本会自己往前走。上面说了，同一台机器十几分钟内版本号就变了。Codex 有自更新能力，配置里也有启动时检查更新的开关。子命令和选项在版本之间是会增删的——在 codex-cli 0.147.0 上，cloud 和 exec-server 还带着 [EXPERIMENTAL] 标签，app-server 和 remote-control 带 [experimental] 标签，这些东西下个版本长什么样谁也保证不了。一条几个月前的命令，参数名对不上是常态。

二是猜错了不一定报错。在 codex-cli 0.147.0（Windows 11）上有个实测很能说明问题：执行 codex -s bogus-mode，它会明确顶回来：

error: invalid value 'bogus-mode' for '--sandbox <SANDBOX_MODE>'
  [possible values: read-only, workspace-write, danger-full-access]

For more information, try '--help'.

这种”顶回来并列出合法取值”是最理想的情况。但同一台机器上另一个实测就没这么友好了：执行 codex -c model_reasoning_effortt=high --strict-config exec --help（注意 effortt 是故意多打了一个 t），命令正常打印了 help，没有报未知字段错误。说明 --strict-config 的校验发生在真正加载配置去跑会话的时候，--help 这类不进入会话的路径根本不触发。

结论很直接：别指望工具在每条路径上都替你挡住拼写错误。参数长什么样，去问它自己。

第二步：脚本往哪儿放（三个环境分开写）

codex completion 的官方说明是”生成 shell 补全脚本”，也就是说它的产出是一段脚本文本，怎么让 shell 加载它，是 shell 那边的事，跟 Codex 无关。

下面两段先说清楚性质：它们是按各家 shell 的通用做法组合出来的示例，completion 子命令具体接受什么参数未逐项实测。命令里的 codex completion <SHELL> 属于占位示意，<SHELL> 乃至这个调用形式本身，都以你本机 codex completion --help 的实际输出为准；除了这一处占位，其余每一行都可以直接复制执行。

Git Bash / macOS / Linux 的 bash 系

mkdir -p ~/.codex-shell
codex completion <SHELL> > ~/.codex-shell/codex-completion.sh
echo '[ -f ~/.codex-shell/codex-completion.sh ] && . ~/.codex-shell/codex-completion.sh' >> ~/.bashrc

三行分别在干什么：第一行建一个专门的目录，别把生成物丢进 ~/.codex/——那是 CODEX_HOME，里面是配置、凭据、会话落盘这些由 Codex 自己管理的东西，混进手写文件只会给以后的排查添乱。第二行把脚本落成文件，而不是每次启动 shell 都现调一次 codex，避免拖慢开终端的速度。第三行的 [ -f ... ] && 是必要的守卫：哪天你把这个文件删了或者换了机器，没有这层判断，每开一个终端都会报一次错。

PowerShell

New-Item -ItemType Directory -Path "$HOME\.codex-shell" -Force | Out-Null
codex completion <SHELL> | Out-File -FilePath "$HOME\.codex-shell\codex-completion.ps1" -Encoding utf8
if (-not (Test-Path $PROFILE)) { New-Item -ItemType File -Path $PROFILE -Force | Out-Null }
Add-Content -Path $PROFILE -Value 'if (Test-Path "$HOME\.codex-shell\codex-completion.ps1") { . "$HOME\.codex-shell\codex-completion.ps1" }'

四行的对应关系和 bash 那边是一一对得上的：第一行建目录，-Force 让目录已存在时不报错，| Out-Null 是把 New-Item 返回的对象吞掉、别刷屏；第二行把脚本写进同一个目录（这两行的路径必须一致，写岔了执行就会因为目录不存在而失败）；第三行确保 $PROFILE 这个文件真的存在——很多机器上它只是一个路径，文件本身从没被创建过，不先建就没法追加；第四行才是真正的”开关”，外面那层 Test-Path 和 bash 里的 [ -f ... ] 是一个作用。

PowerShell 这段之所以要单独拎出来，是因为 Windows 上 Git Bash 与 PowerShell 是两套独立的补全体系，在其中一个里装好并不会让另一个跟着生效，两侧要分别装、分别验。

产出物长什么样

装完之后，你手上应该多出两样东西，都是可见、可查的：

一个补全脚本文件，落在你自己指定的路径上（示例里是 ~/.codex-shell/ 下）。它是纯文本，可以打开看，也可以进版本库——但建议别进，理由在下面”什么情况不适用”里说。
shell 配置文件里多出的一行加载语句。这一行是唯一的”开关”，出问题时先看它还在不在、路径对不对。

注意区分：这跟 codex exec 的产出物完全是两码事。codex exec 那边有 --json（事件以 JSONL 打到 stdout）和 -o, --output-last-message <FILE>（把 agent 的最后一条消息写到文件），那些是任务结果。补全脚本不产生任何任务结果，它只影响你按 Tab 时终端的反应。

怎么验收：拿子命令表当对照清单

这是这件事上最实在的一步，很多人装完就”感觉好了”，其实只对了一半。

**验收点一：顶层子命令补不补得出来。**新开一个终端（务必新开，老终端不会重新读配置），敲 codex 然后按 Tab。在 codex-cli 0.147.0 上，顶层子命令至少应该覆盖这些：exec（别名 e）、review、login、logout、mcp、plugin、mcp-server、app-server、remote-control、app、completion、update、doctor、sandbox、debug、apply（别名 a）、resume、archive / unarchive / delete、fork、cloud、exec-server、features。

拿这份清单去比对，比”看着有反应就算成”靠谱得多。如果补出来的条目明显少于这份清单，八成不是补全没装上，而是脚本是照着旧版本生成的。

**验收点二：选项级别补不补。**试试 codex -s 后面按 Tab。如果你的 shell 补全做到了值级别，这里应该能给出 read-only、workspace-write、danger-full-access 三个取值——这三个是实测报错信息里 [possible values: ...] 逐字列出的合法值。补不出来也不代表装错了，值级补全支不支持要看该版本生成的脚本本身，这一条只作参考。

**验收点三：换个终端再试一遍。**Windows 上尤其要试：Git Bash 一次，PowerShell 一次。

最容易出错的几步，按发生概率从高到低：

没有新开终端。改了 ~/.bashrc 或 $PROFILE 却在老窗口里试，永远是没反应。
加载语句写进了不生效的那个配置文件。bash 系的 ~/.bashrc 和登录 shell 读的文件不一定是同一个，PowerShell 的 $PROFILE 在不同宿主下也指向不同文件——先 echo $PROFILE 确认路径再动手。
脚本是旧版本的快照。这是最隐蔽的一个，单独讲。

那个最容易被忽略的坑：补全脚本是版本快照

codex completion 生成的是当次那个版本的补全脚本。生成完它就是一个静态文件，不会跟着 Codex 一起更新。

而前面说过，同一台机器上十几分钟内 codex --version 就从 0.131.0 变成了 0.147.0。这两件事撞到一起，结果就是：你的 Codex 悄悄升级了，补全脚本还停在几个版本前。表现出来的症状特别容易误判——新加的子命令补不出来，你以为是自己记错了命令名；某个选项 Tab 出来但实际执行报错，你以为是 Codex 的 bug。

处置办法也简单，就是把”重新生成”这件事和”版本变了”绑在一起。一个可行的做法是：一旦 codex --version 的输出和印象里不一样，或者出现”help 里有、Tab 补不出来”的情况，就重跑一遍第一步和第二步，覆盖掉旧脚本。判断依据永远是 codex --help 的实时输出——它是当前这个二进制文件的真相，补全脚本只是它的一份拷贝。

什么情况不适用

**一、你主要在桌面应用、IDE 扩展或云端用 Codex。**这些面上根本没有”shell 补全”这回事，这篇对你没用。顺带一提，官方文档在排查条目里明确提到过一个现象：功能在 CLI 有、桌面应用没有，原因是两个面的 Codex 版本不同，官方给的做法是分别查版本——CLI 用 codex --version，macOS 应用用 /Applications/Codex.app/Contents/Resources/codex --version。桌面应用与云端这部分我没有实测，属于官方文档口径。

**二、CI 和自动化脚本里。**那些地方跑的是 codex exec 这类非交互命令，没人按 Tab，补全一点价值都没有，反而多一个需要维护的文件。要把非交互跑法固化下来，该用的是 --skip-git-repo-check、--ignore-user-config 这类明确的选项，不是补全。

**三、别把生成的脚本 commit 进项目仓库。**它是”某个人某台机器某个版本”的快照，进了仓库就会随着大家各自的自动升级迅速过期，而且没人会记得去更新它。要在团队里统一，统一的应该是”怎么生成”这个动作，不是生成物。

四、别指望它能替你校验配置。补全补的是命令行，不是 ~/.codex/config.toml 里的键名。前面那个 model_reasoning_effortt 的实测已经说明，配置键拼错了在 --help 路径上是不会被拦的。真要确认配置有没有被正确加载，用 doctor：在 codex-cli 0.147.0（Windows 11）上，故意执行 codex -c 'features=[unclosed' doctor --summary，命令并没有崩溃退出，doctor 照常跑完，但 Notes 区里明确出现了一行：

✗ config       config could not be loaded - Fix the reported config error, then rerun codex doctor.

所以”改完配置没生效”的第一步永远是跑 doctor 看这一行，跟补全没有半点关系。

五、别用 Tab 出来的东西反推功能状态。想知道某个特性能不能用，去看 codex features list——它列出特性名、所处阶段和当前生效值，在 codex-cli 0.147.0 上观测到的阶段有 stable、under development、experimental、deprecated、removed 五种。这里有个容易误读的地方：removed 阶段的特性仍然会出现在列表里，而且部分 removed 项的生效值是 true。这说明 “removed” 指的是这个开关本身不再需要控制、行为已经固化，不等于功能没了。补全帮不了你判断这些，只有 features list 能。

补全这东西的收益不在于”少敲几个字母”，而在于你不再需要在记忆和文档之间来回切换。前提是你得知道它随时可能过期，并且知道过期时长什么样。上面那份子命令清单，存一份下来当对照表，比什么都实用。