读懂 Codex CLI：从仓库结构追踪一次 Agent 循环
阅读终端 Agent 的源码，容易一开始就陷入目录和类型名称。更有效的入口是沿着一次任务走：用户输入在哪里被接收，模型请求怎样构造，工具调用由谁执行，执行结果又怎样回到对话。Codex CLI 的 Rust 实现会随版本调整，目录名称和边界应以你检出的仓库为准；本文给出阅读方法，帮助你验证架构，而不是把某个提交的结构当作永恒事实。
从入口找到会话边界
先看仓库 README 和启动入口，搜索命令行参数解析、会话创建以及主循环。画出“终端输入—会话状态—模型请求—事件输出”的最短路径。遇到抽象层时，沿调用点向下看，而不是只读类型定义。记录关键函数及其调用者，这比从头通读整个仓库更容易建立心智模型。
拆开 Agent 循环
一个典型循环会收集上下文、向模型发送请求、处理文本或工具调用，再将工具结果加入会话继续运行，直到完成或等待用户。检查代码中停止条件、错误分支、取消信号与重试逻辑：它们决定 Agent 是否会重复执行、如何恢复以及何时把控制权交还给人。观察日志和事件类型，也能看出 UI 与核心执行逻辑之间的边界。
追踪工具调用的安全边界
工具接口通常把模型提出的动作转换为可执行请求，但不应把模型输出直接等同于用户授权。跟踪 shell、文件编辑或 MCP 调用经过哪些权限检查，哪些操作会暂停等待批准，拒绝后状态如何处理。做源码实验时使用临时仓库和无敏感数据，先理解默认权限，再运行会写文件或联网的操作。
用小实验验证阅读结论
选择一个只需读取文件的简单任务，加入日志或断点观察请求与结果；再尝试一个需要确认的操作，比较事件路径。一次只改一个变量，并记录检出的 commit。若仓库已调整模块名，可以使用符号搜索和 Git 历史找到职责迁移，避免引用旧文章中的路径造成误导。
阅读时的限制
源码只能说明特定版本的实现，不能保证托管服务、模型端行为或未来版本相同。不要把内部类型视为稳定 API，也不要为了理解循环就关闭安全检查。优先查看官方仓库、版本标签和贡献文档，再把结论写成“在此提交中”的观察。