Codex CLI 使用笔记

Codex CLI 可以理解成一个能进项目里干活的开发助手。它不只是回答问题，还能读代码、改文件、跑命令、看错误输出，然后继续往下处理。

这类工具很多，这篇主要记录 Codex CLI。它适合放在本地仓库里用：查问题、改代码、整理文档、做一些重复但需要判断的工程任务。

这篇只记最常用的流程。官方 Codex 文档入口是 <https://developers.openai.com/codex>，完整说明以官方文档为准，这里不展开所有安装方式。

安装

有 Node.js 和 npm 的环境，直接装：

npm install -g @openai/codex

装完看一下命令是否可用：

codex --version

如果提示 codex: command not found，一般是 npm 的全局命令目录不在 PATH 里。这个按自己机器的 Node/npm 配置处理即可，不在这里展开。

登录

第一次用之前先登录：

codex login

有浏览器的机器会走正常网页登录。远程服务器或者无头环境可以用设备码：

codex login --device-auth

登录信息会保存在本机的 Codex 配置目录里。这里要注意，~/.codex/auth.json 是敏感文件，不要提交到 Git，也不要粘贴到聊天、工单或日志里。

启动

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

cd /path/to/project
codex

如果只是想让它执行一个明确任务，也可以用非交互方式：

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

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

常用命令

日常够用的命令不多：

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

进入 Codex 交互界面后，常用的是这些 slash command：

/status
/model
/review
/exit

其中 /status 很实用，可以看当前 thread、上下文使用情况和 rate limit。

显示上下文统计

长任务里最容易忽略的是上下文。上下文快满时，Codex 可能会压缩历史；压缩不是坏事，但如果正在做复杂修改，提前知道上下文状态会更稳。

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

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

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

如果想看更详细的信息，进入 Codex 后直接输入：

/status

使用习惯

我的习惯是把 Codex 当成一个会动手的同事，而不是搜索框。命令示例里会同时保留 PowerShell 和 Bash，方便在 Windows、本地 Linux、WSL 或服务器环境里切换。

简单问题可以直接问；涉及代码修改时，最好给它清楚的边界，比如要改哪个目录、不要碰哪些文件、完成后跑什么检查。仓库里有稳定规则的话，写进 AGENTS.md，比每次口头重复更可靠。

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

另外，Codex 改完以后还是要看 diff。它能省很多时间，但最后负责的人还是自己。

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

使用 Codex 时看到很多后台进程，或者看到背景信息窗口里已经使用了很多 token，容易误以为每次对话都读取了大量仓库内容。实际需要分开看两个问题：一个是本机运行了哪些工具进程，另一个是当前模型上下文里装进了哪些文本。

MCP server、插件运行时、代码索引服务和浏览器控制桥接都可能表现为本地进程。这些进程主要负责给 Codex 暴露能力，例如：

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

这些进程会占 CPU 和内存，但它们的存在本身不代表上下文窗口已经被填满。上下文窗口主要被文本内容、工具说明、对话历史、工具输出、图片和文件引用占用。

上下文主要由什么占用

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

1. 系统和开发者规则

   Codex 会注入安全、工具调用、协作模式、文件编辑、Git、前端设计等规则。这些是基础成本，用户一般看不到完整内容。

2. 当前仓库指令

   仓库根目录和子目录下的 AGENTS.md 会进入上下文。稳定规则写进仓库，比每次口头重复更可靠，但规则也会占用上下文预算。

3. 可用工具和插件说明

   启用的 MCP、插件、apps、skills 会把一部分工具 schema 和触发说明暴露给模型。工具越多，固定上下文成本越高。

4. 已使用 skill 的完整说明

   skill 列表只是一部分成本；当任务触发某个 skill 后，Codex 还会读取该 skill 的 SKILL.md。回答 Codex 自身机制、云服务或框架当前用法时，这类读取是合理的，但仍应只读必要章节。

5. 对话历史和工具输出

   每次命令输出、搜索结果、长日志、长文档片段都会进入上下文。宽泛搜索或一次性输出过多行，是最容易无谓膨胀上下文的来源。

6. 图片和文件引用

   图片本身以及文件路径、截图上下文也会增加背景信息占用。

排查工具进程

先看当前启用的 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 自身机制时，读取官方 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 或长日志。

CodeGraph 的边界

CodeGraph 是给 Agent 使用的代码结构索引服务。它会在仓库下维护 .codegraph 数据库，并通过 MCP 服务提供符号、调用关系和文件级上下文。适合用在这些场景：

• 快速理解函数、组件、模块之间的调用关系。
• 判断一个改动会影响哪些调用方。
• 在大仓库里先获得结构化上下文，再决定读哪些文件。

它不适合替代所有搜索。简单文本搜索、明确文件定位、文档编辑、脚本运行，仍然直接用 rg、git diff、Get-Content 更直接。

如果任务管理器中出现多个后台进程，或者某个 CodeGraph 子进程持续高 CPU，要先区分它是项目服务、MCP stdio server、CodeGraph shim，还是带仓库路径的索引进程。排查时可以先看命令行：

Get-CimInstance Win32_Process |
  Where-Object { $_.CommandLine -match 'codegraph|mcp' } |
  Select-Object ProcessId,ParentProcessId,CreationDate,CommandLine |
  Format-List

Linux 或 macOS 下可以这样看：

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

真正需要关注的是类似 codegraph.js serve --mcp --path <repo> 的仓库服务进程。进程命令行里是否带 --path <repo>，是判断它是否对应当前仓库的关键证据。

如果 .codegraph/daemon.log 持续刷文件监听错误，例如：

[CodeGraph] File watcher error { error: 'Error: EPERM: operation not permitted, watch' }

同时 CPU 长时间增长，就可能是 CodeGraph watcher 在 Windows 上进入不健康状态。此时可以在确认目标仓库路径后终止对应进程；这只影响结构化索引能力，不会破坏仓库文件，也不会影响 rg、构建、测试、Git diff 等普通操作。

常用边界判断：

• 代码调用链、组件影响面、复杂模块关系：优先考虑 CodeGraph。
• 查字符串、文件名、Markdown、配置：优先用 rg 和直接文件读取。
• 发现 CodeGraph 或 MCP 相关进程持续高 CPU：先查进程命令行和 .codegraph/daemon.log。
• .codegraph 是本地索引数据目录，数据库、日志、PID、socket 等文件不应作为项目交付内容提交。

是否需要安装或关闭 MCP

从上下文控制角度看，关闭工具不是第一优先级。更直接有效的是减少无关读取和长输出。只有当启动速度、内存、CPU 或工具列表固定成本明显影响使用时，才考虑关闭不常用能力。

反过来说，没有安装某个 MCP 也不代表 Codex 就不能干活。大多数文章整理、Git 操作、配置定位、小范围代码修改，直接用 rg、git diff、文件读取和必要的命令输出就够了。MCP 更像增强能力，不是必备前置条件。

我现在会保留的增强项主要是两个：

• context7：查询库、框架、SDK、CLI、云服务的当前文档。只靠模型记忆很容易碰到过时 API，尤其是 Next.js、React、云服务配置、CLI 参数这类变化快的内容。把它接成 MCP 后，Codex 可以按需查文档，不需要每次把大段文档或搜索结果塞进上下文。
• codegraph：理解代码结构、符号关系、调用链和影响范围。大仓库里它比纯文本搜索更适合作为第一轮定位工具，可以先让 Agent 知道模块之间的关系，再决定具体读哪些文件。

这两个工具确实会增加一些本地进程和固定工具说明成本，但对我的使用方式来说是值得的：context7 降低了写出过时用法的概率，codegraph 降低了在复杂代码关系里盲目 rg 和反复读文件的成本。

不过它们不是所有任务的入口。改 Markdown、查固定字符串、看配置、做单文件小改动时，rg 和直接文件读取仍然更快。判断原则很简单：

• 问题依赖“当前版本文档”：用 context7。
• 问题依赖“代码结构关系”：用 codegraph。
• 问题只是“文本在哪里”：用 rg。
• 问题只是“这个文件怎么改”：直接读文件和看 diff。

可按需关闭的插件：

• 文档、表格、演示、PDF 类插件；
• 浏览器、Chrome、Computer Use 类插件，前提是不需要 Codex 做页面验证或浏览器自动化。

看到很多后台进程，首先应判断它们是 MCP/插件进程还是项目服务；看到背景信息 token 较高，首先应判断上下文里是否积累了长工具输出和无关文档。对当前工作方式来说，最需要约束的是读取范围和输出长度，而不是简单关闭所有工具。

安装 Context7

context7 推荐接入 Codex 的 MCP。它的价值不是“让 Codex 会写框架代码”，而是在需要当前文档时，让 Codex 先查资料再回答。比如排查 Next.js 15 App Router、React 新 API、云服务配置或 CLI 参数时，比凭旧经验更稳。

npx ctx7 setup --codex

安装后可以用一个明确的版本文档问题试一下，例如：

查询 Next.js 15 App Router 的当前文档，并说明 route handler 的缓存行为

如果 Codex 能通过 Context7 先定位官方文档，再基于文档回答，就说明链路基本可用。

安装 CodeGraph

codegraph 适合给代码仓库建立结构索引。安装后，在有 .codegraph/ 索引的仓库里，Codex 可以优先用它理解符号、调用链和影响范围；没有索引的仓库则继续用普通文件搜索。

curl -fsSL https://raw.githubusercontent.com/colbymchenry/codegraph/main/install.sh | sh

安装完成后，进入目标仓库初始化索引：

cd /path/to/project
codegraph init

也可以显式传入路径：

codegraph init /path/to/project

初始化后仓库里会出现 .codegraph/ 目录。只要当前仓库有这个索引，Codex 就可以优先调用 CodeGraph 来理解代码结构。比如这个仓库已经有 .codegraph/，遇到代码定位、调用链、影响面分析时，就可以先用 CodeGraph，再决定是否继续读具体文件。

常用命令：

codegraph status
codegraph sync
codegraph explore "这个模块的入口和调用关系是什么"
codegraph node "src/path/to/file.ts"
codegraph query "handleSubmit"
codegraph callers "handleSubmit"
codegraph callees "handleSubmit"
codegraph impact "handleSubmit"
codegraph files
codegraph help
codegraph help explore

我最常用的是 codegraph explore 和 codegraph node。前者适合问一个代码问题，让它一次性返回相关符号、源码片段和调用路径；后者适合读取某个符号或文件的行号内容。status 用来确认索引状态，sync 用来增量更新索引。

是否需要初始化取决于仓库规模和任务类型；如果只是写文章或改少量配置，不初始化也没关系。真正需要跨模块理解代码时，再让仓库拥有 .codegraph/ 索引更合适。

参考

• 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
• CodeGraph CLI Reference：<https://github.com/colbymchenry/codegraph/blob/main/site/src/content/docs/reference/cli.md>