第 12 卷
# 从项目根目录验证 codex -a never "Summarize the current instructions."
# 验证子目录的override是否生效 codex -C services/payments -a never \ "Show which instruction files are active."
行为上的验证更可靠。§03那个任务里，AGENTS.md要求「用中文回复」「总结里列出改动的文件名」，它的最终总结两条都做到了。
Codex每次运行都会重建指令链，不存在缓存。如果指令看起来不对，重启Codex即可。
常见问题排查
问题排查方向
| Codex没加载任何指 | 确认你在预期的仓库目录中，会话里用/status看Directory和Agents.md两行。确认文件 |
|---|---|
| 令 | 非空。 |
| 加载了错误的指令 | 检查目录树上层是否有AGENTS.override.md，重命名或删除override文件。 |
| Fallback文件名不生 | 确认config.toml中拼写正确，然后重启Codex。 |
效
指令被截断提高 project_doc_max_bytes，或把长规则拆分到子目录。
花叔的经验：AGENTS.md不要写太长。短而准比长而全有用。我自己写作项目的规则文件改了很多轮，全局那份和写作库那份现在都在10KB上下，里面不少条目后面都写着是哪天、因为什么事加的。每条规则最好都对应一个真实踩过的坑，提前想象的「万一需要」先别写。从你和Codex协作中真正出过问题的地方开始写，一条一条攒，这份文件自然会长成你需要的样子。
§06 桌面App里的Codex：多线程的指挥中心
Codex in the ChatGPT Desktop App
同时跑几个任务、让agent操作本机的其他App、在内置浏览器里看它改的网页、用手机远程审批，这些是桌面App比CLI多出来的部分。7月起，它住在ChatGPT桌面App里。
CLI有两类事天然不擅长：同时盯好几个agent，和让agent操作图形界面。桌面App就是为这两类事做的。
它现在在哪
2026年7月9日（App版本26.707）起，原来独立的Codex App并进了ChatGPT桌面App。打开ChatGPT桌面 App，侧边能切三块：
Chat：普通的ChatGPT对话。
Work：ChatGPT Work，用和Codex同源的能力处理非编程的日常任务。
Codex：本章讲的这一块，可以设成打开App时的默认视图。
Work和Codex共用同一份用量和额度。老的Codex App用户是原地更新过来的，项目和线程都在。
平台上，macOS和Windows是正式版，Linux（Ubuntu、Debian、Fedora，x64和ARM64）从8月11日起有预览版。装了CLI的话， codex app 会打开桌面App，没装就打开安装程序；在CLI会话里输入 /app，可以把当前
这个会话接到桌面App里继续。
这一章的App功能这次没有截图实测，内容按官方changelog和文档整理，日期是changelog里的日期。
项目、线程、三种模式
App里可以加多个项目，每个项目对应一个代码库目录。7月23日起一个项目可以挂多个文件夹，其中一个是主文件夹，AGENTS.md、skills和config.toml只从主文件夹里找。
每个项目下面开多个线程，一个线程就是一次对话、一个任务。新建线程时选它在哪跑：
| 模式 | 工作方式 | 适合 |
|---|---|---|
| Local | 直接在项目目录里改 | 常规开发，改了马上能看效果 |
| Worktree | 在一个独立的git worktree里改 | 几件事并行，互不干扰 |
| Cloud | 在云端环境里跑（§07） | 电脑关了也要继续，或者要特定环境 |
Worktree：并行的基础
git worktree能让同一个仓库同时有好几个独立的工作目录。选Worktree模式，Codex会给这个线程建一个独立的checkout，agent在里面改，你本地的代码不受影响，你可以照常写代码、跑服务。
干完之后两条路：直接在worktree上建分支、提交、推送、开PR；或者用Handoff把改动移回Local，在你熟悉的环境里检查。Handoff由Codex处理底层的git操作。要注意一条git本身的限制：同一个分支同一时间只能被一个checkout使用，worktree上建了 feature/a，Local就不能同时checkout它，这时候用Handoff，别手动
切分支。
CLI现在也能做这件事（ codex --worktree、 /worktree，§04），区别是App把几个线程摆在一个窗口里，谁在跑、谁在等你批准，一眼能看到。
一个典型的并行用法
假设一个Web项目同时有三件互相独立的事：做一个新的设置页、把一个接口从REST改成GraphQL、修首页的一个bug。
1.每件事开一个Worktree线程，需求写清楚，设置页的需求可以用 @ 引用设计文档。
2.三个线程并行跑。审批多的话，权限选Approve for me，让自动审查处理低风险请求（§04）。
3.哪个先完成先看哪个的diff，没问题就开PR，或者Handoff回Local做集成测试。
App的diff面板能按未提交、整个分支、最近一轮切换范围，能在具体某一行上加评论，再让它「处理inline评论，改动尽量小」。评论锚定在行上，比在对话框里描述「第几行那个函数」准确。
子agent
除了你手动开几个线程，一个线程里的主agent也可以自己派子agent。当前版本子agent默认开启， codex features list 里 multi_agent 是stable。配置在 config.toml 的 [agents] 下：
[agents] max_concurrent_threads_per_session = 6# 旧名 max_threads 仍可用 default_subagent_model = "gpt-6-luna"
default_subagent_reasoning_effort = "medium"
每个自定义角色单独一个TOML文件，放在 ~/.codex/agents/（个人）或 .codex/agents/（项目）：
name = "planner"
description = "把大任务拆成可并行的小任务，自己不动手"
developer_instructions = "你是协调者，把任务拆给子agent，自己不直接改代码。"
model = "gpt-6.1-sol"
角色文件里写 sandbox_mode、 approval_policy 不会生效，子agent的沙盒和审批跟着父会话走。想让它「不