Codex CLI 使用笔记

Codex CLI 是一个能直接进项目干活的开发助手。除了回答问题，它还可以读代码、改文件、运行命令，并根据错误输出继续处理。

这篇只记录我使用 Codex CLI 的经验。它适合在本地仓库中排查问题、修改代码、整理文档，也能接手一些重复但仍需要判断的工程任务。

这里只写常用流程。完整的安装和配置说明请看 Codex 官方文档。

安装

已经安装 Node.js 和 npm 的话，可以直接运行：

npm install -g @openai/codex

安装后先确认命令可用：

codex --version

如果提示 codex: command not found，通常是 npm 的全局命令目录没有加入 PATH，需要检查本机的 Node/npm 配置。

启动

进入项目目录后直接启动：

cd /path/to/project
codex

如果任务很明确，也可以使用非交互模式：

codex exec "阅读 README，并总结这个项目的启动方式"

我平时更常用交互模式：可以一边看它的判断，一边补充上下文；任务复杂时，也方便随时打断或调整方向。

Shell 不是无关细节

Codex 可以调用终端，但命令文本最终由宿主提供的 Shell 解析。PowerShell、Git Bash、WSL Bash 和传统 cmd.exe 处理路径、引号、管道、环境变量、脚本后缀和命令查找的方式并不相同。忽略这一层，很容易把 Shell 的启动或初始化问题误判成 Codex、项目代码或其他 CLI 的问题。

在 Windows 上，我现在默认使用 MSI 安装的 PowerShell 7：

C:\Program Files\PowerShell\7\pwsh.exe

可以先确认当前进程确实是预期的 PowerShell：

$PSVersionTable.PSVersion.ToString()
(Get-Process -Id $PID).Path
(Get-Location).Path
Get-Command pwsh, git, node, npm, rg |
  Select-Object Name,Source,Version

我曾遇到过一次启动故障。当时使用的是 Microsoft Store 目录下的 PowerShell 7.6.3：

C:\Program Files\WindowsApps\Microsoft.PowerShell_7.6.3.0_x64__8wekyb3d8bbwe\pwsh.exe

它在 Codex 的受管终端中连续启动失败，而且错误发生在 PowerShell 执行命令之前：

CreateProcessAsUserW failed: 1312
指定的登录会话不存在。可能已被终止。

这类错误通常出在宿主创建进程时使用的 Windows 登录会话或令牌上，和 PowerShell 脚本、仓库代码没有直接关系。改用 MSI 路径后，同一环境里的 PowerShell 7.6.3、当前目录和普通命令都恢复正常。如果 PowerShell 能在自己的终端中启动，但 Codex 仍然报 1312，可以先重启 Codex 刷新登录会话，再确认它实际调用的 pwsh.exe 路径。

# 安装 MSI 版本的 PowerShell 千万千万千万不要用 MSIX 安装包的 PowerShell
winget install --id Microsoft.PowerShell --source winget --installer-type wix

Git Bash、WSL Bash 和裸 `bash`

安装 Git for Windows 后通常会有 Git Bash，但直接输入 bash，启动的不一定是它。我在本机运行：

Get-Command bash | Select-Object Name,Source

返回的是：

C:\Windows\System32\bash.exe

这个程序是 WSL 启动器，不是 Git Bash。Git Bash 的实际路径是：

C:\Program Files\Git\bin\bash.exe

所以需要 Unix Shell 时，最好明确选择 Git Bash，不要只写含义不确定的 bash。登录模式也会影响结果：我在本机以非登录模式启动 Git Bash 时，/usr/bin 没有正确加入 PATH，head、cygpath 等命令无法找到，npm 甚至误触发了 WSL。改为登录模式后，MSYSTEM=MINGW64 和完整的 PATH 得到初始化，Git、Node、npm、ripgrep 以及路径转换都恢复正常。

进入 Git Bash 后可以这样确认环境：

printf 'bash=%s\n' "$BASH_VERSION"
printf 'msystem=%s\n' "$MSYSTEM"
printf 'shell=%s\n' "$SHELL"
printf 'path=%s\n' "$PATH"
command -v git node npm rg pwsh
cygpath -w "$PWD"

$SHELL 只是一个环境变量，不一定对应当前进程。判断 Bash 环境时，$BASH_VERSION、$MSYSTEM、PATH 和具体命令的解析结果更可靠。

我现在的选择

Windows 本机仓库、文件系统、进程、注册表和系统工具：默认 PowerShell 7。
项目自带 .sh、文档明确使用 POSIX 语法或命令依赖 sed、awk、head：显式使用 Git Bash，并确保登录环境已经初始化。
真正需要 Linux 用户空间、Linux 包或 Linux 路径语义：使用已经安装发行版的 WSL，不把 WSL 启动器和 Git Bash 混为一谈。
Linux 或 macOS：按项目约定使用 Bash、Zsh 或其他本机 Shell。
cmd.exe：只作为 PowerShell 或 Bash 无法创建进程时的临时诊断后备，不作为默认开发环境。

排查 Shell 问题时，我会按下面的顺序逐层确认：

宿主能否创建 Shell 进程。先看 CreateProcessAsUserW、登录会话、权限和可执行文件路径。
Shell 是否完成初始化。检查 Profile、登录模式、PATH、MSYSTEM 和其他环境变量。
命令是否被正确解析。检查引号、空格、中文路径、管道、重定向、通配符，以及 PowerShell 和 POSIX 的语法差异。
目标程序是否真的启动。确认 Git、Node、npm、ripgrep 或项目脚本的版本与实际路径。
前面四层都正常，再查仓库代码、依赖和配置。

codex doctor 可以辅助检查本地安装、配置、认证、运行时、Git 和终端问题，但进程创建与 Shell 解析仍要自己判断。

常用命令

日常使用主要是下面几个命令：

codex --version
codex login
codex doctor
codex
codex exec "你的任务"

进入交互界面后，我常用这些斜杠命令：

/status
/model
/review
/exit

/status 可以查看当前任务、上下文用量和速率限制。

显示上下文统计

长任务很容易忽略上下文用量。剩余空间不多时，Codex 可能压缩历史。压缩本身没有问题，但在复杂修改中，提前知道还剩多少上下文更方便安排后续工作。

可以在 ~/.codex/config.toml 中固定显示底部状态栏：

[tui]
status_line = ["model-with-reasoning", "context-remaining", "current-dir"]

保存配置并重新打开 Codex 后，底部会显示模型、剩余上下文和当前目录。

更详细的信息可以通过 /status 查看：

/status

我的本地配置

Codex 的个人配置文件位于：

$HOME/.codex/config.toml

这份配置会影响所有受信任的项目。我把日常开发限制在工作区沙箱内，同时允许沙箱访问网络：

model = "MODEL_NAME"
model_reasoning_effort = "medium"
approvals_reviewer = "auto_review"

sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = true

workspace-write 允许 Codex 修改当前工作区，network_access = true 则允许沙箱访问 npm、文档服务和其他开发资源。danger-full-access 会放开更多系统限制，我在日常开发中通常用不到。

我还开启了底部状态栏：

[tui]
status_line = ["model-with-reasoning", "context-remaining", "current-dir"]

状态栏会持续显示当前模型、推理强度、剩余上下文和工作目录。修改配置后需要重新打开 Codex，已有会话不会自动加载全部新配置。

MCP 配置

我的本地配置保留了三个 MCP：Context7、CodeGraph 和 OpenAI Developer Docs。基本配置如下。认证 token 不要写进文章、仓库或截图：

[mcp_servers.context7]
url = "https://mcp.context7.com/mcp"

[mcp_servers.context7.http_headers]
CONTEXT7_API_KEY = "REDACTED_CONTEXT7_API_KEY"

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]

[mcp_servers.openaiDeveloperDocs]
url = "https://developers.openai.com/mcp"

Context7、CodeGraph 和 OpenAI Developer Docs 的安装及使用边界已经拆成独立文章：

这里保留 Codex 的通用配置入口。API Key、登录凭据和其他 token 只放在本机配置或密钥管理系统中，不提交到 Git，也不复制到公开文章。

MCP 是增强能力，不是每项任务的前置条件。修改 Markdown、查固定字符串、看配置或做单文件小改动时，rg 和直接读取文件通常更快。

具体安装命令、自动触发规则和调用成本放在对应 MCP 文章中维护，避免 CLI 总览重复保存一份容易过期的配置。

Agent Skill

Skill 的查找、审阅、安装、管理和常用清单已经统一整理到我如何使用 Agent Skill：查找、安装与实践。这里不再重复保存一份容易分叉的命令和说明。

项目信任和记忆

我还启用了记忆功能，并把当前项目标记为受信任：

[features]
memories = true

[memories]
disable_on_external_context = true
generate_memories = true
use_memories = true

[projects."/path/to/trusted-project"]
trust_level = "trusted"

项目设为 trusted 后，Codex 才会加载其中的 .codex/ 配置。只对自己确认过的仓库开启它；面对不熟悉的项目，不要为了省事直接设为信任。

使用习惯

我习惯把 Codex 当成一个会动手的同事，而不是搜索框。命令示例也不默认使用 Bash：Windows 本机任务优先用 PowerShell 7，遇到 POSIX 脚本再明确切换到 Git Bash。代码块会标注实际使用的 Shell，免得把不同语法混在一起。

简单问题直接问就行。涉及代码修改时，最好说明边界，例如修改哪个目录、哪些文件不要动、完成后运行什么检查。稳定的仓库规则可以写进 AGENTS.md，不用每次重复交代。

涉及提交身份、提交边界、测试是否应该沉淀成回归用例这类协作规则，可以单独参考《Agent 协作中的提交与测试边界》。

Codex 改完后，我仍然会看一遍 diff。它能省时间，但最终确认改动的人还是自己。

工具进程和上下文不是一回事

使用 Codex 时，如果看到很多后台进程，或发现背景信息已经占用了不少 token，很容易以为每次对话都读取了大量仓库内容。其实这是两件事：本机运行了哪些工具进程，以及当前模型上下文中装进了哪些内容。

MCP server、插件运行时、代码索引服务和浏览器控制桥接都可能表现为本地进程。它们负责向 Codex 提供不同能力，例如：

codegraph：为仓库建立代码图谱，支持查符号、调用链、影响范围等结构化代码问题。
context7：按需查询库、框架、SDK、CLI、云服务的当前文档。
文档类插件：处理 PDF、Word、PPT、表格等文件。
浏览器类插件：控制内置浏览器、Chrome 或桌面应用。

这些进程会占用 CPU 和内存，但不一定占满上下文窗口。上下文主要消耗在文本、工具说明、对话历史、工具输出、图片和文件引用上。

上下文主要由什么占用

一次对话的 token 用量通常来自以下几部分：

系统和开发者规则

Codex 会注入安全、工具调用、协作模式、文件编辑、Git 和前端设计等规则。这是每次对话都会承担的基础成本，用户通常看不到完整内容。
当前仓库指令

仓库根目录和子目录下的 AGENTS.md 会进入上下文。把稳定规则写进仓库很方便，不过规则本身也会占用上下文预算。
可用工具和插件说明

启用的 MCP、插件、App 和 Skill 会向模型提供工具 schema 与触发说明。工具越多，固定成本越高。
已使用 skill 的完整说明

Skill 列表只占一部分。任务触发某个 Skill 后，Codex 还会读取对应的 SKILL.md。这在查询 Codex 机制、云服务或框架当前用法时很有用，但仍应控制读取范围。
对话历史和工具输出

命令输出、搜索结果、长日志和文档片段都会进入上下文。宽泛搜索和一次输出太多内容，是最常见的浪费。
图片和文件引用

图片、文件路径和截图附带的信息也会占用上下文。

排查工具进程

先看当前启用的 MCP：

codex mcp list

如果要确认本机工具进程来自哪里，可以先在 Windows 上查看 node.exe 的命令行：

Get-CimInstance Win32_Process -Filter "name = 'node.exe'" |
  Select-Object ProcessId,CommandLine

Linux 或 macOS 下可以用：

ps -eo pid,ppid,pcpu,pmem,args |
  grep -Ei 'node|codegraph|mcp|codex' |
  grep -v grep

命令行参数可以帮助区分普通 node.exe、CodeGraph 服务、MCP stdio server、Codex runtime 和项目自己的服务。不要只看进程名，还要留意仓库路径、--mcp、serve 等参数。

另行检查 node_repl：

Get-Process node_repl -ErrorAction SilentlyContinue |
  Select-Object Id,ProcessName,CPU,WorkingSet,Path

Linux 或 macOS 下可以继续按进程名过滤：

ps -eo pid,ppid,pcpu,pmem,args |
  grep -Ei 'node_repl' |
  grep -v grep

node_repl.exe 是 Codex 自带的 runtime，不是项目中的 Node 服务。

控制上下文输出

Codex 自身机制可能随版本变化，这类问题值得查官方 manual。但不要上来就搜整份文档，否则很容易产生大量最后用不到的输出。我的做法是：

先用目录或关键词定位章节；
只读取 MCP、plugins、skills、app runtime 相关片段；
搜索结果限制条数和上下文行数；
对工具输出设置较小的输出上限；
避免把长日志、长文档、完整配置一次性塞进上下文。

普通 Git 和文件任务也是如此。上下文窗口不是日志池；一次常规的合并、清理或验证，如果直接塞入完整的 git status、全量路径、git diff --check 警告和批量删除输出，很快就会消耗掉大量空间。

我通常先看计数和摘要：

git status --short | Measure-Object
git diff --stat
git diff --name-only | Select-Object -First 50
git ls-files <generated-dir> | Measure-Object

Bash 下对应写法：

git status --short | wc -l
git diff --stat
git diff --name-only | head -50
git ls-files <generated-dir> | wc -l

需要确认具体问题时，再按路径过滤或抽样：

git status --short -- AGENTS.md
git diff --cached --stat -- .archive
git diff --name-only --diff-filter=U

Bash 下这些 Git 参数本身不变：

git status --short -- AGENTS.md
git diff --cached --stat -- .archive
git diff --name-only --diff-filter=U

确实需要保留完整证据时，可以写入临时文件；对话中只回传数量、关键路径和少量失败样例。提交代码时同样如此，除非任务明确要求，不必默认展示完整 diff、git show 或长日志。

参考

OpenAI Codex Docs：<https://developers.openai.com/codex>
OpenAI Codex Sandbox：<https://developers.openai.com/codex/concepts/sandboxing#prerequisites>
OpenAI Codex Manual：/codex/quickstart.md
OpenAI Codex Manual：/codex/auth.md
OpenAI Codex Manual：/codex/config-basic.md
npm：@openai/codex
Next.js Docs：<https://nextjs.org/docs>
Next.js Docs for LLMs：<https://nextjs.org/docs/llms.txt>
MDN Web Docs：<https://developer.mozilla.org/>
DevDocs：<https://devdocs.io/>
CodeGraph CLI Reference：<https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/reference/cli.md>

文章

编程笔记

AI Playground

部署记录

开发工具

系统折腾

Codex CLI 使用笔记

安装

登录

启动

Shell 不是无关细节

Git Bash、WSL Bash 和裸 `bash`

我现在的选择

常用命令

显示上下文统计

我的本地配置

MCP 配置

Agent Skill

项目信任和记忆

使用习惯

工具进程和上下文不是一回事

上下文主要由什么占用

排查工具进程

控制上下文输出

参考

编程笔记

AI Playground

部署记录

开发工具

系统折腾

Codex CLI 使用笔记

安装

登录

启动

Shell 不是无关细节

Git Bash、WSL Bash 和裸 bash

我现在的选择

常用命令

显示上下文统计

我的本地配置

MCP 配置

Agent Skill

项目信任和记忆

使用习惯

工具进程和上下文不是一回事

上下文主要由什么占用

排查工具进程

控制上下文输出

参考

Git Bash、WSL Bash 和裸 `bash`