Codex 配置排障与工作流中心

配置排障

按常见问题分类，遇到哪个查哪个：

1. config.toml 只读/无法保存 — 从路径查找、权限检查、编辑器占用到项目配置覆盖，六步排障流程。
2. 修改后不生效 — 检查 CODEX_HOME、项目配置覆盖、CLI 参数和 TOML 语法。
3. TOML 常见错误 — 字符串引号、数组格式、重复键定义。

Codex 配置排障的通用思路

遇到 Codex 配置问题时，不要直接删除 .codex 目录。按照以下顺序排查通常能解决 90% 的问题：确认修改的是正确的用户级配置文件（~/.codex/config.toml）、检查文件只读属性和目录权限、排除编辑器占用、检查项目级配置覆盖（项目/.codex/config.toml）、验证 TOML 语法、检查 CODEX_HOME 环境变量、重新启动 Codex。每步都有可回滚的备份方案。

Codex 日志文件为什么会异常增长？

logs_2.sqlite 是 Codex 的本地日志数据库。正常情况下体积稳定，但在以下情况可能持续增长：数据库内部锁定导致 WAL 文件不断追加、杀毒软件或云同步软件持续扫描文件、Codex 进程异常退出后遗留未合并的 WAL。处理时务必先退出 Codex、备份整个 .codex 目录、将日志文件重命名为 .old 而非直接删除、重启 Codex 观察是否恢复正常。

什么是好的项目交接文档？

Codex 每次新线程没有上下文记忆。一份好的交接文档能让新线程在几分钟内理解项目现状，而不是花半小时从 git log 和代码中推测。核心要素：项目背景与目标用户、当前版本与阶段、技术栈、已完成功能及对应文件、当前进行中的工作及风险、待办清单按 P0/P1/P2 分级、运行命令与环境变量说明、验收标准。交接文档放 docs/project-handoff.md，长期规则放 AGENTS.md。

日志与磁盘

1. logs_2.sqlite 持续增长 — 安全退出、备份、重命名 .old、恢复步骤。
2. WAL 文件持续写入 — 与主数据库一起处理，不要只删 WAL。
3. 磁盘空间不足 — 检查 PSDrive、目录权限和文件占用。

工作流与规范

1. 项目交接文档模板 — 可直接复制的 Markdown 模板，覆盖背景、技术栈、状态、待办和验收标准。
2. AGENTS.md 配套建议 — 长期规则放 AGENTS.md，阶段任务放交接文档。
3. 新线程接手提示词 — 先理解、后计划、再执行的标准流程。

FAQ

• Q：config.toml 修改后为什么不生效？
  A：可能是项目级配置覆盖、CLI 参数优先、CODEX_HOME 指向其他路径、Codex 未重启或 TOML 语法错误。建议按六步排障流程逐步排查。
• Q：可以直接删除 logs_2.sqlite 吗？
  A：不建议。优先重命名为 .old，确认 Codex 正常后再删除。运行时删除可能导致数据损坏。务必先退出所有 Codex 进程。
• Q：为什么需要项目交接文档？
  A：Codex 每次新线程没有上下文记忆。交接文档能让新线程快速理解项目现状，减少重复沟通。文档格式建议用 Markdown，放在项目根目录。
• Q：AGENTS.md 和交接文档有什么区别？
  A：AGENTS.md 放长期稳定规则（不要删除数据、不要跳过验收等），交接文档放当前阶段的具体信息（进度、风险、待办）。
• Q：Codex 项目配置覆盖用户配置怎么办？
  A：检查项目根目录的 .codex/config.toml。项目配置只有在项目被 Codex 信任时才加载。可以通过 Codex 设置调整信任策略。

相关页面