Codex CLI 的命令和参数越来越多，安装自动补全后却按 Tab 没反应，通常不是 Codex 本身无法运行，而是补全脚本没有被当前 shell 加载。Bash、Zsh、Fish 和 PowerShell 的初始化方式不同，配置文件也不在同一个位置。只执行一次 `codex completion` 只能把脚本输出到终端，并不会自动永久安装。排查时先确认当前使用的 shell，再看脚本是否生成、配置是否加载、补全框架是否初始化，这比反复重装 Codex 更快。

一、先确认当前终端真正使用哪个 shell

很多人以为自己在 Windows Terminal 里就一定使用 PowerShell，或看到 macOS 终端就默认是 Zsh。终端只是窗口，里面可以运行 Bash、Zsh、Fish、PowerShell，甚至通过 WSL 进入另一套 Linux 环境。先查看当前进程和 shell 版本，再决定生成哪一种补全脚本。

如果在 WSL 里运行 Codex，应按 WSL 内部的 Bash 或 Zsh 配置，而不是修改 Windows 用户目录下的 PowerShell 配置。VS Code 集成终端也可能为不同项目选用不同 profile。补全只在某个窗口有效，往往说明你改的是其中一种 shell，而另一个窗口启动了别的 shell。

二、理解 codex completion 做了什么

`codex completion bash`、`codex completion zsh`、`codex completion fish` 和 `codex completion powershell` 会输出相应 shell 能理解的补全定义。它不会替你判断配置文件位置，也不会强行写入启动脚本。直接运行后看到大量文本是正常现象，说明生成器工作了，但还没有完成加载。

首次测试可以把生成结果临时加载到当前会话。临时加载成功后，再把同样逻辑放进 shell 的启动文件。这样能把“Codex 生成失败”和“配置文件没有执行”分开。如果命令本身报 unknown subcommand，先确认当前 `codex` 版本及命令来源，不要急着修改 shell 配置。

三、Bash 补全要注意加载顺序

Bash 通常需要补全功能已经启用，再加载 Codex 脚本。不同发行版可能通过 `bash-completion` 包提供通用框架，用户配置常放在 `~/.bashrc`，登录 shell 还可能读取 `~/.bash_profile`。在配置里加入补全命令后，应重新打开 shell，或明确重新加载对应文件。

如果普通终端能补全，远程 SSH 或容器中不能补全，检查那些环境是否安装了相同 Codex 版本，并确认 HOME 指向哪个目录。不要把主机生成的绝对路径直接复制进容器。补全脚本应由实际运行 Codex 的环境生成，避免版本和路径不一致。

四、Zsh 出现 compdef not found 怎么处理

Zsh 的常见报错是 `command not found: compdef`。这通常表示补全系统尚未初始化，而不是 Codex 脚本损坏。先执行 `autoload -Uz compinit && compinit`，再加载 `codex completion zsh` 的输出。顺序反过来，脚本引用 `compdef` 时就找不到函数。

使用 Oh My Zsh、Prezto 或其他框架时，还要看框架何时调用 `compinit`。把 Codex 补全放在框架初始化之后通常更稳。若每次启动都很慢，不要重复执行昂贵的初始化，可以把生成的补全文件放到 `fpath` 下，并按框架习惯缓存。

如果大家想体验一线 AI 编程模型 codex 和 claude，用它们完成命令行配置、代码修改和测试审查，可以参考以下教程文档进行接入配置，接入配置好后即可使用。文档教程：https://my.feishu.cn/wiki/NIgLwuuj1ibzJIkLGM0cgVNinzg

五、Fish 应放进正确的 completions 目录

Fish 对补全文件有自己的目录约定。临时执行脚本可以验证语法，但要长期生效，通常应保存到用户配置目录的 `completions` 子目录，并使用与命令匹配的文件名。若文件放错层级，Fish 启动不会报明显错误，却也不会自动发现。

检查时可让 Fish 显示配置目录，确认文件确实属于当前用户。公司电脑可能设置了不同的 XDG 配置路径，照抄网上固定路径会失效。更新 Codex 后如果新参数不出现，重新生成一次补全文件，避免一直使用旧版本脚本。

六、PowerShell 要检查执行策略和 profile

PowerShell 可以把补全脚本加载逻辑写入 `$PROFILE`。但 `$PROFILE` 不是一个固定文件：Windows PowerShell、PowerShell 7、VS Code Host 和不同用户范围可能对应不同路径。先在当前窗口输出 `$PROFILE`，确认你编辑的是正在使用的那一个。

如果加载时报脚本执行被禁止，要区分本地 profile 被阻止，还是生成内容本身有问题。企业设备的执行策略可能由管理员控制，不应为了一个补全功能全局放宽安全策略。可以先在当前进程范围测试，确认有效后再按组织规则处理签名或允许范围。

七、codex 命令来源必须一致

同一台机器可能同时存在 npm 全局安装、独立安装包、旧目录残留和 WSL 版本。终端实际调用的 `codex` 若不是你刚更新的那一份，生成的补全选项也会滞后。用系统命令查看所有命令路径，并记录版本，确保运行和生成脚本使用同一个可执行文件。

Windows 上尤其要留意 PATH 顺序。PowerShell 找到旧的 `codex.cmd`，而另一个终端找到新可执行文件，就会出现一边支持某参数、一边补全列表没有该参数。先清理来源冲突，再重建补全，比在多个 profile 里叠加配置更可靠。

八、配置文件写了却没有加载怎么查

在补全配置前后加入一条临时、无副作用的标记，重新打开终端，确认启动文件确实执行。若没有执行，检查当前 shell 是登录模式还是交互模式，以及它读取的是 `.bashrc`、`.zshrc` 还是其他文件。确认后删除调试标记，保持配置干净。

还要检查配置语法。上一行缺少引号或括号，可能让后面的 Codex 补全根本没有机会运行。用 shell 自带的语法检查工具验证启动文件，避免把错误归咎于补全命令。团队共享 dotfiles 时，应在不同操作系统上做条件判断。

九、用最小动作验证补全是否正确

重新启动 shell 后输入 `codex`、一个空格，再按 Tab，观察是否出现子命令；输入 `codex completion` 后再按 Tab，观察是否列出 shell 类型；输入带短横线的参数前缀，检查参数候选。不要只看 Tab 有没有声音，因为终端设置可能把候选显示方式改成菜单或列表。

如果子命令有补全而新参数没有，通常是脚本版本旧；完全没有候选，则更像加载问题；其他命令也不能补全，应先修复 shell 的通用补全系统。按这三种表现分类，排查范围会小很多。

十、给多环境保留可维护的配置

长期使用时，建议在 shell 配置中写清楚补全来源，并避免每次启动都联网或执行复杂安装。更新 Codex 后重新生成脚本，保留一次版本检查。团队文档可分别给出 Bash、Zsh、Fish 和 PowerShell 的入口，不要把四种配置混成一段让新人猜。

最终验收包括：当前 shell 已确认、Codex 路径唯一、补全脚本能生成、初始化顺序正确、profile 确实加载、新开窗口按 Tab 有候选。自动补全只是效率工具，不值得通过关闭整机安全策略来换取。把环境和加载链路理顺后，它通常会稳定工作。