Codex 编程 Agent
Codex 和聊天式 AI 的分水岭，在于它能真的改你的文件、跑你的命令。所以它绕不开的问题不是"聪明不聪明"， 而是边界划在哪——哪些目录可写、哪些命令要问你、什么时候能出网。 本专题共 85 篇，不复述官方文档的功能清单，而是回答四件事： 这个配置项到底管什么、这条命令什么时候用、报错了怎么判定、该选哪一档。 内容依据 官方文档 整理，核对日 2026-08-09；标注「本机实测」的部分基于 codex-cli 0.147.0 / Windows 11 环境下的只读命令输出。 桌面应用与云端部分为官方文档口径，非本机实测。产品功能、模型与价格以官方最新说明为准。
Codex 的六个使用面：一张图看懂该用哪个
第一次接触 Codex（OpenAI Codex）时最容易卡住的不是安装，而是不知道该从哪个入口进。本文按官方文档站的六个分面——桌面应用、CLI、IDE 扩展、Codex cloud、Web、Codex Remote——给出一条从你自己的处境倒推的选择路径，说明每一步为什么这么选、选错了会在哪里出问题，并标清哪些是本机实测、哪些只是官方文档口径。
上手与入门
四种安装渠道怎么挑、两种登录方式的边界、第一次用先把哪五件事定下来，以及 GPT-5.4 退役前要改的地方。
第一次用 Codex CLI：先把这五件事定下来
装完 Codex CLI 就直接敲第一句话，多半会在权限、模型、登录方式上返工。这篇按顺序讲清第一次使用前该定下来的五件事：确认你在用哪一个 codex、选登录方式、选沙箱模式、选审批策略、选模型，每一步都说明为什么这么做、做错了会在哪一环出问题，并给出可直接执行的只读检查命令。
ChatGPT 登录还是 API Key：Codex 两种认证的边界
第一次给 Codex CLI 做认证时，最容易糊涂的不是命令怎么敲，而是这台机器上的 Codex 到底从哪个账户扣费、受谁的规则管。这篇按上手顺序讲清两种认证方式各自的登录命令、凭据落在哪、怎么验收、没浏览器的机器怎么办、登录失败先看哪个日志，以及团队想固定走某一条路时该动哪几个配置键。
Codex 怎么用？从安装到跑通第一个任务的全流程教程
OpenAI Codex 是在终端里干活的 AI 编程代理。本文带你从安装、登录、审批模式到用 AGENTS.md 配置项目规则，一步步上手 Codex 并跑通第一个真实任务，附新手常见坑与答疑。
Codex CLI 四种安装方式怎么选，装完第一件事是跑 doctor
官方给了独立安装脚本（macOS/Linux 与 Windows 各一条）、npm、Homebrew 四种装 Codex CLI 的方式。这篇按「你手上有什么」倒推该选哪一种，然后讲清楚装完为什么要先跑 codex doctor、登录该走 ChatGPT 还是 API Key，以及每一步做错了会在哪里翻车。
GPT-5.4 八月三十一号从 Codex 退役：迁移前要改的五处，以及漏改会怎样
官方明确 GPT-5.4 与 GPT-5.4 mini 于 2026 年 8 月 31 日从 Codex 退役，并给定了替换模型。这篇按第一次做迁移的顺序，逐一讲清官方点名的五个位置该怎么改、每一步为什么要改，以及漏掉某一处之后会出现什么后果。
配置与机制
config.toml 的分层与覆盖、沙箱与审批、权限档、特性开关的五个阶段——搞懂机制才能自己做决定，而不是照着教程抄一遍。
`never` 不等于放开权限：Codex 里最容易混的三组概念
把 Codex 的 never 当成放开权限是最常见的误解：审批策略管的是要不要问你，沙箱管的是能不能做，两套机制彼此独立、互不决定。本文拆开审批策略与沙箱模式、沙箱档位与网络边界、Windows 两种沙箱实现这三组最容易混的概念，逐组给出判断依据、可自查的诊断命令，以及一份从需求倒推该动哪个开关的决策清单。
Codex `config.toml` 全景：它在哪、有几层、该先改哪几个键
Codex CLI 的配置项多到一屏放不下，新手最常见的问题不是「怎么写」而是「改哪个、改在哪一层、改完为什么没生效」。本文按官方 Configuration Reference 梳理配置文件的位置与叠加关系，给出四组优先该动的键，拆解三个名字容易理解反的开关，并附上本机 0.147.0 实测的两条验证路径。
Codex 的日志、SQLite 状态库与 OTel 遥测：先分清三层，再决定开什么
Codex CLI 的运行痕迹分散在 log 目录、sessions 会话文件和几个 SQLite 库里，磁盘占用会悄悄涨到 GB 级。本文梳理 log_dir、sqlite_home、history.persistence 与整套 otel.* 导出键位，给出该查哪一层、该关哪一项、遥测要不要开的判断依据。
Codex 多代理配置怎么定：并发上限、子代理默认模型与角色定义
Codex CLI 的多代理由 agents 这一组配置键控制：并发线程上限、子代理默认模型与推理强度、每个角色的说明与独立配置层。本文按官方配置参考逐键说清取值与默认值，重点讲官方没给默认值的那几个键该怎么定、旧别名 max_threads 与新键的关系、子代理选便宜模型时的成本依据，以及改完配置后用 features list 和 doctor 验证生效的完整方法。
Codex 联网搜索的四种模式：默认 `cached` 既不是关闭也不是实时
Codex 的 web_search 默认值是 cached，既不是关闭也不是实时。本文讲清四档取值该怎么选、CLI --search 的真实作用范围与会话级边界、三个已弃用的 features 老开关怎么迁移，以及改完配置后用哪条命令确认它真的加载生效了。
Codex 沙箱三种模式怎么选：从「能不能改我的文件」倒推
Codex CLI 的 read-only、workspace-write、danger-full-access 到底差在哪？本文不照抄官方释义，而是从「你允许它改哪些文件、要不要出网、有没有管理员权限」三个问题倒推出该选哪一档，顺带讲清沙箱与审批策略这对最容易混淆的概念，以及 Windows 上 elevated 与 unelevated 的取舍和排查入口。
Codex 审批策略拆解：三档字符串与五个细粒度开关怎么选
Codex CLI 的 approval_policy 既能写成 untrusted/on-request/never 三档字符串，也能写成带五个开关的表。这篇讲清两种写法各自能做到什么、never 为什么不等于放开权限、五个细粒度开关关掉之后到底是自动拒绝还是自动放行（哪些官方写了、哪些没写），以及怎么用 codex doctor 确认当前真正生效的是哪一档。文中给出可直接复制的 TOML 片段与命令行覆盖写法，并说明受管配置为什么会盖掉你本地的改动。
Codex 生命周期钩子怎么配：事件、匹配器组与 Windows 专属覆盖
Codex CLI 的生命周期钩子由 features.hooks 开关、hooks.json 或内联 hooks 表组成，事件下面还分匹配器组和处理器两层数组。本文按官方配置参考逐层拆开这套结构，说清事件名为什么不能靠猜、additionalContextLimit 默认 2500 带来的实际约束、Windows 专属的 commandWindows 覆盖为什么必须存在、钩子来源的信任边界在哪，以及改完配置之后该用哪几条只读命令确认它是不是真的生效了。
Codex 特性开关的五个阶段：removed 不等于功能没了
codex features list 会把每个特性的阶段标成 stable、under development、experimental、deprecated、removed 五种之一，很多人看到 removed 就以为功能被删了，但本机实测里有 removed 项的生效值仍然是 true。这篇讲清五个阶段各自代表什么、阶段标签和生效值为什么会错位、开关该写在会话里还是写进配置文件，以及改完之后用哪两条命令验收。
Codex 自定义权限档：按目录和域名给 AI 发通行证
沙箱三档只能选整体松紧，管不了「只让它写 src、只让它连一个域名」。这篇讲清 Codex CLI 里 permissions 权限档的配置结构：extends 继承链、filesystem 的三态取值、network 的三层开关，以及 -p 与 -P、权限与审批这两组最易混淆的概念怎么分辨。
Codex CLI 的 `--profile`：给不同项目挂不同配置层
一台机器上同时开着实验仓和生产仓，用同一份 config.toml 迟早出事。这篇讲清 Codex CLI 顶层选项 -p/--profile 的叠加机制、文件名规则，以及它和 -P/--permission-profile、-c 三者的分工边界，并给出用 doctor 验证配置到底有没有加载成功的实测方法和判断依据。
Codex CLI 的 `-c` 到底覆盖了什么：四条规则与一次配置加载失败的实测
Codex CLI 的 -c 选项能在不改 config.toml 的前提下临时覆盖配置，但它的行为由四条规则叠加而成：覆盖用户配置、点号表示嵌套、值按 TOML 解析、解析失败则回落成字面字符串。最后一条最容易被读成「怎么写都不会报错」。本文用本机只读命令的实测输出，说明写错时错误会被推迟到哪一步、怎么用 doctor 一眼看出来，以及 --strict-config 拦不住什么。
Codex CLI 的 TUI 定制：状态栏、主题、快捷键与解绑到底怎么配
Codex CLI 的界面几乎每一处都能在 config.toml 的 tui 段里改。本文按官方配置参考逐条列出键名、取值与默认值，重点讲三处容易翻车的细节——alternate_screen 的 never 和审批策略的 never 不是一回事、解绑快捷键必须赋空数组而非删行、改完后用哪条命令确认配置真的加载了。
Codex Memories 的 11 个配置键：它为什么有时候不生成记忆
Codex CLI 的 Memories 不是「AI 自动记住了」，而是一条被总开关、两个读写开关、六个数值阈值和两个模型键卡住的流水线。本文逐个拆开这些键的含义与判断依据，给出「没生成记忆」时从总开关一路查到额度阈值的排查顺序，并说明哪些场景应该主动关掉它。
Codex shell 环境变量策略：哪些变量会被带进子进程
Codex CLI 的 shell 工具派生子进程时，究竟会把你终端里的哪些环境变量带过去？本文拆开 config.toml 里 shell_environment_policy 这一组键，讲清 inherit 三个取值怎么选、ignore_default_excludes 默认 true 为什么反而是保留带 KEY/SECRET/TOKEN 的变量、set 与旧版 exclude 的关系，以及在 Windows 上改完配置该用哪条命令确认它真的被加载。
场景实战
每篇按同一套写：命令怎么写、产出物落在哪、怎么验收、什么情况不适用。以 codex exec、review、MCP 接入这些能落到流水线上的用法为主。
`codex review` 的三种评审范围怎么挑：--uncommitted、--base 与 --commit
codex review 提供了三个划定评审范围的选项，选错范围会让评审结果整个跑偏。本文按实际场景讲清 --uncommitted、--base、--commit 各自覆盖什么、命令怎么写、产出物往哪里接、验收时要盯哪几处，以及哪些活儿不该指望这三个范围来兜底。
把 `codex exec --json` 接进自己的流水线：命令怎么写、产出怎么接、怎么验收
想让 Codex 在 CI 或本地脚本里跑完就把结果交给下一个程序，靠的是 codex exec 的 --json 与 -o 两个选项。这篇给出可直接复制的完整命令、Windows 与 Git Bash 两套写法、逐个选项为什么在这，以及产出物怎么接、上线前该检查哪几处、哪些活儿根本不该这么干。
把回复变成脚本能解析的 JSON：`codex exec --output-schema` 实战
想让 Codex CLI 的产出直接进脚本、进流水线，靠正则去抠自然语言迟早翻车。这篇讲怎么用 codex exec 的 --output-schema 配合 -o 与 --json 拿到结构化产物：完整命令怎么写、每个选项为什么在这、产出物落在哪、验收要盯哪几行、以及哪些活儿压根不该这么干。
给 Codex 接一个 MCP server 的完整流程：配置、启动超时与工具审批怎么调
把一个 MCP server 接进 Codex CLI，真正卡人的不是那段配置，而是默认只有 10 秒的启动超时、60 秒的工具超时，以及 disabled_tools 会盖掉 enabled_tools 这类顺序陷阱。这篇按官方配置参考逐键拆开怎么写，给出可直接复制的 stdio 与 HTTP 两种配置块，再用本机只读命令的实测输出说明接完之后去哪儿验收、哪一步最容易翻车、什么活儿不该这么干。
给 Codex CLI 装上 shell 补全：一份不靠猜的落地清单
Codex CLI 自带 completion 子命令用来生成 shell 补全脚本，但支持哪些 shell、参数怎么写会随版本变，抄别人的命令很容易踩空。这篇给出先自查再落地的完整步骤、Windows 与类 Unix 侧分开的放置方式、拿子命令全表做验收对照的办法，以及自动升级后补全脚本变成旧版快照这个最容易被忽略的坑。
提交前自查工作流：`codex review --uncommitted` 到底该怎么写
提交代码前想让 Codex 先过一遍，但它到底看哪几类改动、沙箱要不要收紧、审批策略选哪个、结果落在哪、哪一步最容易翻车？本文给出可直接复制的命令与逐个选项的取舍理由，配上四个验收检查点与不适用场景，均基于 codex-cli 0.147.0 / Windows 11 的只读命令输出与官方文档口径。
用 `-i` 把截图和设计稿带进 Codex 首轮指令
UI 截图、设计稿、报错弹窗这类东西用文字转述很费劲，Codex CLI 的 -i 选项能把图片文件直接附在首轮指令上。本文给出交互式与 codex exec 两种可直接复制的命令写法，逐个解释选项为什么要加，说明 --json 与 -o 的产出物落在哪里，并给出四步验收顺序：先看 features list 里 view_image 的阶段与生效值，再用 doctor 确认配置真的加载成功，最后讲清哪些场景不该这么干。
用 `codex exec` 把任务写成可重复执行的命令
交互式对话跑完就散了，没法沉淀成团队资产。这篇讲怎么用 codex exec 把一次性对话固化成可复制、可进脚本的命令：完整命令怎么拼、顶层选项与 exec 选项分别写在哪、--json 与 -o 的产出物落在哪，以及哪些活儿压根不该这么干。
用 `notify` 让 Codex 跑完主动叫你：配置写法、通知脚本与验收清单
交给 Codex 一个长任务之后盯着终端干等，是最浪费的一种等待。这篇讲清 config.toml 里 notify 这个键该怎么配、Windows 与类 Unix 的路径写法差在哪、通知脚本第一版为什么应该只做「把收到的内容原样落盘」而不是急着解析字段，最后给出一份照着走就能排掉八成问题的验收清单和不适用场景。
在 CI 里跑 `codex exec`：非仓库、免配置与超时这三件事
把 Codex CLI 塞进流水线，绕不开三个坑：工作目录不是 Git 仓库会被拦、runner 上没有你本机那份 config.toml、以及跑到一半没人知道该等多久。本文按官方选项与配置键给出可直接复制的完整命令、产出物落点、验收检查项，以及哪些活儿根本不该交给非交互模式。
Codex 插件实战：三个 marketplace 怎么读、插件怎么装怎么停
Codex CLI 的插件有三个 marketplace、四个子命令和好几层开关，装了不生效多半不是装错，而是被某一层关掉了。这篇讲：怎么用 codex plugin list 摸清家底、STATUS 列怎么读、features 与 config.toml 里的启停键各管什么、改完怎么验收。
Codex 的 AGENTS.md 该写什么、写多长、放在哪一层
AGENTS.md 是 Codex 读项目自定义指令的入口，但真正决定它「能不能被读到、能读多少」的是 config.toml 里的几个键。本文讲清控制项目文档读取的几个配置键，给出可直接改的配置块、验收要检查的四个位置，以及哪些约束根本不该写进 AGENTS.md。
Codex 会话管理实战：归档、取消归档、删除与按名字找回
Codex CLI 的会话会一直落盘，本机 doctor 报出 405 个 rollout 文件占 3.07 GB。这篇讲清 resume、fork、archive、unarchive、delete 这几条命令各管哪一段，会话文件落在哪个目录，归档和删除之后拿什么验收，以及哪些场景根本不该指望它们兜底。
Codex 会话续跑与分叉实战：resume、`--last` 与 fork 怎么用才不丢上下文
一次会话没干完就关了终端，第二天怎么接着跑？这篇把 Codex CLI 的会话续跑与分叉讲透：resume 默认选择器与 --last 的取舍、exec 里的非交互续跑、fork 用来做同一起点的多方案对比、resume 时工作目录归属由 tui.resume_cwd 决定，以及会话落盘在哪、怎么验收、哪些情况根本没法续。
Codex CLI 用 `--add-dir` 让 agent 同时读写两个目录
代码在一个目录、产物要落到另一个目录，是 Codex CLI 日常最常见的跨目录需求。本文按命令怎么写、产出物落在哪、怎么验收、什么时候别这么干四段，讲清 --add-dir 与 -C 的分工、writable_roots 的配置写法，以及 Windows 沙箱下容易踩的坑。
对比与选型
三档模型的能力与成本差、本地还是云端、桌面应用还是 CLI、订阅档位怎么挑、接第三方模型的协议约束。给决策路径，不罗列参数。
本地跑还是云端跑：Codex 选型先看模型可用性
决定 Codex 该在本地跑还是丢到云端跑，别从「哪个更强」入手。这篇按模型可用性、谁来改文件、有没有管理员权限、预算与会话同步五个岔口，把官方文档里的硬约束串成一条可以照着走的决策路径，并说明每一步判错之后会以什么形式反噬你。
从权限模型看 Codex 与其它编程 agent 的差别：选型前该问清楚的五个维度
选编程 agent 时最难比的不是谁代码写得好，而是它到底能碰你机器上的什么。本文用 Codex CLI 0.147.0 的沙箱模式、审批策略、平台实现、网络控制和权限档五个维度搭一套坐标系，按「只读还是可写、要不要云端、有没有管理员权限、是不是无人值守」五种处境倒推到具体配置，并给出可在本机执行的验收命令与横向选型时该问对方的问题清单。
Claude Code vs Codex：两大终端 AI 编程代理怎么选
Claude Code 和 Codex 都是在终端里干活的 AI 编程代理。本文从模型生态、审批与交互、扩展性、价格和中文支持五个维度实测对比，并按工作流和任务类型给出明确选型建议。
Codex `--oss` 接本地模型：lmstudio 与 ollama 怎么选
Codex CLI 的 --oss 只给了 lmstudio 和 ollama 两个取值，官方没说差在哪。这篇不比参数，而是按预算、数据要不要出本机、要不要让它动文件、有没有管理员权限四个问题，帮你在 ChatGPT 登录、API Key、--oss 本地提供方和自定义 model_providers 之间选出路径。
Codex 订阅档位怎么选：先搞懂 5 小时窗口与消息数口径
选 Codex 订阅档位时，最容易被忽略的不是价格数字，而是官方的用量口径——计量单位是消息数不是 token，窗口是 5 小时滚动窗口，同一档位内的区间跨度还随模型变化。这篇按「要不要跑云端、按订阅还是按 token、预算多少、是不是团队」四个岔口给出决策路径，并说明 sol 与 luna 之间 25 倍的积分单价差距对「要不要上云」这个决定意味着什么。
Codex 积分单价里的三个比例：缓存 10 倍、输出 6 倍、档位 25 倍
Codex 官方积分单价表列了三个模型的 Input、Cached Input、Output 三列数字，与其背下这九个数，不如记住从表里直接算出来的三个比例。这篇按「要不要云端、任务复不复杂、预算卡在哪」的顺序把选型路径走一遍，说明这三个比例分别对应哪个动作，也说清它们管不了什么——比如它们算不出你的月账单。
Codex 接第三方模型怎么选：`model_providers` 与 `wire_api` 只支持 responses 这一关
想让 Codex 用自己的模型端点，很多人直接抄 model_providers 配置，结果卡在协议上。这篇按你的处境倒推该走哪条路：公司发席位、自己按 token 付费、要接自定义端点、还是本地跑；讲清 wire_api 默认且只支持 responses 意味着什么，以及配好之后用 doctor 的哪几行验收。
Codex 接入 DeepSeek 等国产模型配置教程
Codex 默认绑 OpenAI，想换成 DeepSeek 等国产模型省钱又稳定？本文讲清兼容端点的原理、配置文件改 provider 与 base_url 的通用步骤、效果取舍和常见报错排查。
Codex 接入 Kimi、GLM 等兼容 API 模型怎么配
想给 Codex 换上 Kimi、GLM 等国产模型省钱又长上下文？本文讲清自定义 provider 的接入原理、配置文件改法、各家 base_url 与模型标识填法，以及连不上时的排查清单。
Codex 三档模型 sol / terra / luna 怎么选：从你的处境倒推，而不是比参数
gpt-5.6-sol、terra、luna 三档的差别不只是"强一点弱一点"：terra 和 luna 在 Codex cloud 上根本不可用，而三档之间的积分单价差到 25 倍。这篇按四个现实约束——要不要跑云端、要不要它改文件、订阅是哪一档、老配置里还写着什么模型——给出一条能走到底的选型路径，并说明配置该落在哪几个键上。
Codex 推理强度怎么选：UI 档位与配置取值是两套名字
Codex 的推理强度在界面上叫 Light、Medium、Extra High，写进 config.toml 却是 minimal 到 xhigh，我们核对的官方文档页里没有对照表。本文按「改哪一层、跑在哪、预算多少、有没有管理员权限」四个岔路口，把选档拆成一条能照着走的决策路径，并说明改完怎么确认配置真被加载。
Codex 用量与计费：ChatGPT 套餐里的额度怎么算
讲清 Codex 的两套计费逻辑——ChatGPT 套餐内含额度走速率限制窗口、API key 按量计费走 token，以及怎么查用量、额度耗尽怎么办，帮你把账算明白不踩坑。
Codex 桌面应用还是 CLI？从四个处境倒推的选型路径，外加版本口径这个坑
官方对 Codex 桌面应用和 Codex CLI 各自推荐了什么场景，两者的差别不在功能多少，而在你的处境。本文按能不能装应用、要不要脚本化、要不要跨设备接着做、要不要精确控制改文件的权限这四个问题倒推结论，并解释官方排查页里那条「功能在 CLI 有、桌面应用没有」的版本口径差异到底该怎么查、怎么避免误判。
Codex IDE 扩展和 CLI 该怎么分工？从你的处境倒推一条决策路径
纠结 Codex 用 IDE 扩展还是命令行，问法本身就错了。这篇不罗列功能表，而是从四个真实处境倒推——任务要不要无人值守跑完、要不要改本地文件、有没有管理员权限、要不要上云端——逐条给出判断依据，说明官方文档在哪几处已经替你划好了界线，以及 CLI 与其它使用面之间实际存在的三个接缝和一个高频版本坑。
Codex vs Cursor：终端 Agent 还是 IDE 怎么选
Codex 是终端里的自动化代理，Cursor 是边写边改的 AI 编辑器。这篇从交互方式、适用任务、生态价格逐项对比，给出分场景选型结论，并讲清两者怎么搭配用。
Gemini CLI 和 Codex 怎么选？一个额度写在明面上，一个文档是空白
除了额度机制，两者在「出问题时你能不能自救」这一点上差别很大。本文从官方文档完备度这个少有人比的角度切入，给出实际的选择建议。
排查与故障
Windows 沙箱、配置不生效、MCP 启动超时、磁盘占用、登录受阻——按官方文档与本机实测给的判定方法排，官方没给修复方案的地方明说。
「切回官方登录」是怎么实现的：CC Switch 里 official 类预设的机制
切回官方账号听上去像要写入一份官方配置，但在 CC Switch 的源码里恰恰相反：official 预设是一份刻意留空的配置，切过去之后还要专门擦掉残留的第三方凭据。本文按仓库快照逐处标出这套机制落在哪些文件的哪几行。
`--strict-config` 为什么没拦住我的拼写错误：配置校验的触发时机
在 config.toml 里把配置键拼错，加了 --strict-config 却没报错。本文用 codex-cli 0.147.0（Windows 11）的只读命令实测，说清这个开关的校验何时触发、哪些路径不触发，并给出判定命令：doctor 看配置加载没有，features list 核对生效值。
`.codex` 文件夹放错位置：monorepo 里配置不生效的排查路线
队友说好的项目配置在你机器上就是不认，多半不是配置写错了，而是 .codex 文件夹没在项目根，或者你在 monorepo 的子包目录里启动了 Codex。这篇按现象、判定命令、官方处置、验证方法、排除项五步走一遍，顺带讲清楚项目里的 .codex 和用户目录下的 ~/.codex 完全是两码事，别把两边的键混着改。
`~/.codex` 悄悄吃掉几个 GB：rollout 会话与 SQLite 日志的磁盘占用排查
系统盘越用越紧，别忘了翻一眼 Codex 的家目录。本文按排查顺序讲清怎么用 codex doctor 判定占用大头在 rollout 会话还是 SQLite 日志库，官方文档与本机只读命令给出的处置分别有哪些，改完怎么验证，以及哪些迹象说明磁盘满根本不是 Codex 的锅。
`CLAUDE.md` / `AGENTS.md` / `GEMINI.md`：三份文件的同步与回填保护
CC Switch 的 Prompts 功能把提示词写进各个 CLI 的真实配置文件。这篇按源码讲清文件名映射落在哪一行、切换时的回填保护把 live 文件内容存到了哪、全部禁用为什么会把文件写成空串，以及手动导入与首次自动导入的 enabled 默认值为何相反，并给出可自己复现的核查路径。
`codex doctor` 里那行 ✗ config 是什么意思：配置加载失败的判定与处置
改完 config.toml 却发现设置没生效，多数人第一反应是去翻文档找键名，其实应该先跑一次 doctor。本文讲清 doctor 输出里 config 那一行的四种状态符号各代表什么、配置加载失败时它会打出哪句原话、怎么分层定位是基础配置还是命令行覆盖出的问题、处置后如何确认修好，以及哪些情况说明问题根本不在配置加载这一环。
`winget` 不可用时，Codex 的 Windows 沙箱为什么起不来
Windows 上 Codex CLI 沙箱初始化失败，很多人第一反应是去装 bubblewrap，方向就错了。这篇按「现象 → 判定命令 → 官方处置 → 验证 → 排除」的顺序，讲清 winget 这个硬性前置条件卡在哪，怎么用 doctor 和 sandbox.log 确认是不是它，以及哪些报错其实是另外几件事。
版本号自己变了：Codex CLI 自动更新与版本口径排查
昨天 codex --version 还是一个号，今天再敲就变了；文档里写的选项在你机器上找不到，特性阶段也和别人对不上。这篇按现象、判定命令、处置、验证、排除五步走，讲清楚 Codex CLI 的版本从哪来、该以什么为准、doctor 的哪几行能一眼看出装在哪、以及哪些症状其实和版本无关。
侧栏冒出不是 Codex 改的文件？先把 diff 面板切到 Last turn 视图
用 Codex 改代码时，diff 面板里冒出一堆跟本轮任务无关的文件，很容易被误判成 AI 乱动了你的代码。官方给的原因是项目在 Git 仓库里、面板展示的是全部 Git 状态变更，做法是切到 Last turn 视图。本文给出判定命令、处置后的验证步骤，以及五种说明不是这个原因的情况。
服务器上没有浏览器怎么登录 Codex：`--device-auth` 与 1455 端口隧道
SSH 到一台没有图形界面的机器上装好 Codex CLI，登录这一步却卡住——因为 ChatGPT 登录要在浏览器里完成认证。这篇按排查顺序讲：先用哪几条只读命令确认问题真出在「没有浏览器」上，官方给的设备码登录、复制已缓存凭据、转发 1455 回调端口三条路各自适用什么处境，处置完怎么验证，以及哪些迹象说明你其实撞的是别的墙。
改完 `config.toml` 不生效：按这四层覆盖顺序往下查
你在 ~/.codex/config.toml 里改了键，重开会话行为却一点没变。这类问题九成不是键名写错了，而是覆盖层没理清。本文按配置加载、命令行一次性覆盖、profile 叠加、平台与版本差异四层顺序，给出可直接执行的判定命令，并说明每一步处置后该看哪条只读命令的输出来验证。
公司网络下 Codex 登录失败：TLS 代理与 `CODEX_CA_CERTIFICATE` 的排查顺序
家里能登、到公司就登不上，多半卡在办公网的 TLS 代理或私有根 CA。本文按 login status、doctor --summary、codex-login.log 的顺序定位问题层级，再给官方处置：登录前设置 CODEX_CA_CERTIFICATE、设备码登录与 1455 端口转发，并列出何时该掉头查别处。
看懂 `codex doctor` 的每一行：六个分组逐条读法与排查判定
Codex CLI 出问题时第一条该跑的命令是 codex doctor，但它一屏输出里哪一行是真故障、哪一行只是正常的空闲状态，很多人分不清。本文按本机实测到的六个分组逐行拆解 doctor 的输出结构、四种状态符号和结尾统计行，给出「配置没生效」「磁盘被吃光」「连不上」三类现象的判定命令、处置和验证方法，也说清什么情况下问题根本不在 doctor 报的这一行上。
拿不到管理员权限：Codex Windows 沙箱 unelevated 回退模式的取舍
公司电脑没有管理员权限、UAC 提示被策略拦掉，Codex 的 Windows 原生沙箱初始化不起来该怎么办。这篇按排查思路走一遍：先用 doctor 确认卡在哪一步，再看官方给的 elevated 与 unelevated 两种模式差别在哪、配置键怎么写、回退之后拿什么验证边界还在，最后列出几种看着像但其实不是这个原因的情况。
沙箱里文件写不进去：三种模式下的可写边界
Codex 说改好了文件，回头一看磁盘上什么都没变，这类问题九成出在沙箱的可写边界上。本文按排查顺序走一遍：先用 doctor 确认当前沙箱状态，再用 codex sandbox 跑一条无害命令判定写入到底有没有落盘，然后区分三种沙箱模式和三档审批策略的职责，给出扩大可写目录的官方做法，最后列出几种看着像沙箱、其实另有原因的情况。
终端编码 Agent 横评：Claude Code、Codex、Kimi Code 怎么选
三个跑在终端里的编码 Agent 该怎么选？这篇不比"谁更聪明"，而是从额度模型、可预测性、准入前提、退路设计四个真正影响日常使用的维度拆开讲，并给出按人群划分的选型建议和一套双工具兜底方案。
Codex 报 stream disconnected before completion 怎么办？先查是不是模型没解锁
登录之后发第一条消息就断流，可能不是网络问题。issue
Codex 的 /compact 一直失败怎么办？那个 150 秒不是巧合
Error running remote compact task 背后有个可推算的时间结构：30 秒超时乘 4 次重试。本文讲清这个数字的含义、issue 的修复状态，以及为什么「等了两分半才报错」本身就是最有用的线索。
Codex 登录失败怎么解决？ChatGPT 账号与 API Key 排查
Codex 登录认证失败是新手最常踩的坑。本文讲清两种认证方式的区别、浏览器回调失败、API Key 配置位置、套餐没含额度等高频原因，给出可复制的排查步骤。
Codex 会话起错了执行目标：Local、Worktree、Cloud 三条路怎么认、怎么救
起会话时执行目标选错，改动就会落到你没预期的地方——本地工作树、另一个 Git worktree 目录，或者 OpenAI 托管的云端环境。本文按排查顺序给出可执行的判定命令、官方文档给出的处置口径和处置后的验证方法，并列出哪几种相似症状其实另有原因，免得一条道走到黑。
Codex 集成终端卡住不响应：官方给的处置动作与自查顺序
集成终端面板敲了命令没反应，多数人第一反应是重启整台机器。Codex 官方排查页对这条现象只给了一套很短的处置动作，没有给根因。这篇把官方原话讲清楚，再补上一套本机能跑的只读判定命令，帮你分清到底是面板卡了，还是配置没加载、沙箱没起来、登录掉了或者版本对不上，避免一条道走到黑。
Codex 计划任务堆出一大堆 worktree 的判定、清理与验证
用 Codex 跑计划任务一段时间后，仓库旁边冒出一堆 worktree 目录，磁盘越吃越多。这篇按排查路子走一遍：先用 git 自带的只读命令确认这些目录到底是谁建的，再看官方排查页给出的两条处置口径，处置完怎么验证，以及哪几种情况说明你遇到的根本不是这个问题、别在这条路上继续挖。
Codex 沙箱里的命令连不上网：先搞清是哪个开关关的
在 Codex 沙箱里跑命令连不上网，多半不是网线坏了，而是某一层权限开关把出网关掉了。这篇按沙箱模式、network_access、权限档域名策略、Windows 原生沙箱权限模式四层往下排查，每层给出可直接执行的只读判定命令，并说明改完怎么验证生效、出现哪些迹象说明不是沙箱在拦你。
Codex 在 Linux/WSL2 上沙箱不可用，先查 bubblewrap 装没装
Linux 与 WSL2 上的 Codex 沙箱依赖包管理器安装的 bubblewrap（bwrap），缺了它沙箱就起不来。本文按排查顺序走一遍：现象长什么样、用哪几条只读命令确认是不是这个原因、官方给出的处置、处置完怎么验证，以及哪些症状看着像沙箱问题、其实跟 bwrap 无关，免得在错方向上耗时间。
Codex 在 VS Code 里看 Diff 报 Oops, an error has occurred 怎么解决
这条报错的社区办法是降级扩展到一个具体版本并关掉自动更新。本文给出那个版本号、操作步骤，以及原报告者试过但无效的五种做法——知道什么没用同样省时间。
Codex 在 Windows 上沙箱初始化失败：四个成因与官方排查顺序
Codex CLI 在 Windows 上跑的是原生受限沙箱，和 Linux 的 bubblewrap 完全是两套机制，排查步骤不能照搬。本文梳理初始化失败的四类成因：官方列的三条常见原因（UAC 提示被拒、本地用户创建被阻止、防火墙规则受限），加上单列的已知错误 1385。
Codex CLI 安装失败、连不上怎么解决？排查全流程
Codex CLI 装不上、报错、连不上服务器？本文按 Node 版本、npm 权限、网络代理、卸载重装四个环节给你一套可复制的排查命令，从安装到验证一次跑通。
Codex CLI 有的功能桌面应用没有：两个面的版本不一致怎么查
终端里能用的能力，换到桌面应用就找不到，多数人第一反应是自己漏开了开关。官方排查页把这类现象归到「两个面的 Codex 版本不同」。本文给出可直接执行的判定命令、版本号会自己变化的一手实测、处置后如何验证，以及哪几种情况其实和版本无关，别一条道走到黑。
Codex MCP server 启动超时：默认只有 10 秒
MCP server 时好时坏、换台机器就挂，多半不是配置写错，而是撞上了 startup_timeout_sec 默认只有 10 秒这条线。这篇按排查顺序走一遍：怎么用只读命令确认是启动超时而不是别的毛病，官方配置参考里该改哪个键，改完怎么验证，以及哪几种症状明显不是超时、继续调这个值只会白费工夫。
Codex Windows 沙箱报错 1385：沙箱用户建好了，命令却跑不起来
Windows 上跑 Codex CLI，沙箱初始化看着走完了，一执行命令就撞上错误 1385。本文按官方口径拆解这个错误码的确切含义，给出可以直接复制的判定命令、两种沙箱模式各自的取舍与适用前提、官方给出的四步处置顺序及其注意点、处置完成后如何验证沙箱确实还在生效，以及五种看着像它、其实另有原因的情况。
MCP 服务器配了 `required = true`，整个 Codex 就起不来了
给 Codex CLI 的 MCP 服务器配上 required，它初始化失败就会拖着整个 Codex 起不来。本文讲怎么用 doctor 和 mcp list 定位到具体是哪一个服务器，怎么用 -c 临时覆盖而不动配置文件，处置后核哪几处，以及哪些症状其实跟 required 无关。
MCP 工具列表少了几个：`enabled_tools` 与 `disabled_tools` 的生效顺序
配好 MCP server 却发现工具列表比预期少几个。这篇按排查顺序走一遍：先用只读命令分清少的是整台 server 还是单个工具，再看 `enabled_tools` 与 `disabled_tools` 这两张名单的生效顺序，再对照官方配置键排查 server 那一层，最后给出验证动作和说明不是这个原因的迹象。
worktree 上代码跑不起来：`.worktreeinclude` 与初始化脚本怎么排
让 Codex 在 Git worktree 里干活，代码却编不过、跑不起来，多半不是模型的问题，而是 worktree 只继承了 Git 跟踪的文件，依赖和被忽略的本地文件都没跟过去。这篇按现象、判定命令、官方处置、验证、排除五步走一遍，并说清哪些情况根本不是这个原因，免得一条道走到黑。
想把命令行 Agent 真正用进日常开发，而不只是当补全工具？
从 AI 编程实践到 Agent 工程落地，站内有成体系的教程与课程。