bowmanjin

Codex 最佳实践

技 codex，session 10 Bowmanjin

怎么设置合适的 Codex 配置文件？

官网文档

  1. OpenAI 官方 Codex config schema: https://developers.openai.com/codex/config-schema.json
  2. OpenAI 推理参数说明: https://platform.openai.com/docs/guides/reasoning?api-mode=responses#reasoning-summaries

第一优先级

按实用价值排，config.toml 里真正值得你自己配的，通常就这几类。基于当前官方 schema（2026-05-24）来看，大多数人配 6-10 个字段就够了。

  1. model
    1. 默认使用的主模型。
    2. 这是第一优先级配置，决定日常对话、改代码、执行任务默认使用哪个模型。
  2. model_reasoning_effort
    1. 控制推理强度，直接影响：
      1. 思考深度
      2. 响应速度
      3. 成本倾向
    2. 一般建议：xhigh
  3. review_model
    1. 这是一个正式有效的配置项，不是无效字段。
    2. 它只影响 /review 路径，不影响普通对话和普通编码任务。
    3. 适合的场景：
      1. 平时任务用一个更省成本或更快的模型。
      2. 代码审查时单独切到更稳妥的模型。
    4. 如果 review_model 和 model 配成同一个值，那么体感上就不会有区别，但它依然是有效配置。
  4. approval_policy
    1. 控制命令执行审批方式。
    2. 通常建议：
      1. 日常交互开发：on-request。
      2. 需要高度自动化时：再考虑更激进策略。
  5. sandbox_mode
    1. 决定工具执行的权限边界。
    2. 通常建议：
      1. 默认优先：workspace-write。
      2. 不建议默认就给过大的权限。
  6. [sandbox_workspace_write].network_access
    1. 这个参数非常关键。
    2. 它决定在 workspace-write 模式下是否允许联网。
    3. 对于以下场景很重要：
      1. npm install。
      2. 拉依赖。
      3. 访问远程 API。
      4. 查询在线资源。
  7. profiles / profile
    1. 这是非常推荐使用的一组能力。
    2. 原因是你不需要频繁改主配置，而是可以预设多个工作模式。
    3. 常见示例：
      1. fast
      2. deep
      3. review

第二优先级

这些配置不是每个人都必须配，但在常用场景下很值得。

  1. service_tier
    1. 官方 schema 当前可见值包括：
      1. default
      2. priority
      3. flex
    2. 兼容旧值时，某些环境也可能看到 fast。
    3. 适合在你明确想区分服务层级时配置。
  2. web_search
    1. 可选值通常包括：
      1. disabled
      2. cached
      3. live
    2. 如果你经常查下面这些内容，这个参数很有价值：
      1. 最新文档。
      2. 版本信息。
      3. 新闻。
      4. 实时资料。
  3. [tools.web_search]
    1. 如果你已经启用搜索，这里还可以继续控制搜索行为。
    2. 常见参数包括：
      1. allowed_domains
      2. context_size
      3. location
    3. 适合希望搜索结果更干净、更受控的场景。
  4. tool_output_token_limit
    1. 控制工具输出写入上下文的预算。
    2. 对于这些场景很有帮助：
      1. 大仓库。
      2. 长日志。
      3. 很多命令输出。
  5. model_auto_compact_token_limit
    1. 控制长会话里什么时候自动压缩上下文。
    2. 如果你经常长时间连续工作，这个参数很值得配置。
  6. model_verbosity
    1. 控制回答的冗长度。
    2. 如果你觉得输出太啰嗦，或者想明显压缩回答长度，这个参数有实际价值。
  7. developer_instructions
    1. 适合写长期稳定的工作规则。
    2. 常见示例：
      1. 先读代码再改代码。
      2. 默认跑测试。
      3. 输出中文。
      4. 先验证再汇报完成。

按需配置

  1. model_provider
    1. 决定走哪个 provider 配置块。
    2. 如果你有多个兼容 OpenAI 的入口，或者需要切换不同后端，这个值得配置。
  2. [model_providers.<name>]
    1. 这里通常包括：
      1. base_url
      2. wire_api
      3. requires_openai_auth
    2. 如果你要接自定义网关、代理或兼容服务，这部分很重要。
  3. model_context_window
    1. 控制上下文窗口大小。
    2. 通常只有在你明确知道需要覆盖默认行为时才建议改。
  4. default_permissions 与 [permissions]
    1. 适合你想明确设计权限档位时使用。
    2. 常见思路：
      1. 安全模式。
      2. 项目写入模式。
      3. 带网络模式。
  5. shell_environment_policy
    1. 适合想严格控制 shell 继承哪些环境变量时配置。
  6. [projects].trust_level
    1. 如果你会使用项目级 .codex/config.toml，这个很重要。
    2. 它通常影响：
      1. 审批体验。
      2. 沙箱默认行为。
      3. 项目本地配置是否被更积极地采用。

通常不需要重点配置的参数

  1. tui.*
    1. 常见示例：
      1. [tui.model_availability_nux]
      2. notifications
    2. 这些更偏：
      1. 界面状态。
      2. 本地提示状态。
      3. 使用体验细节。
    3. 它们不是核心模型能力配置。
  2. notice.*
    1. 这类一般更偏提示或客户端展示行为，不是模型核心能力。
  3. desktop.*
    1. 更偏桌面端行为控制，而不是模型本身。

不建议随便动的参数

  1. model_instructions_file
    1. 官方 schema 对这个参数有明确保留态度，不建议轻易使用。
    2. 原因是它可能覆盖内建模型指令，导致 Codex 原生行为被破坏。
  2. experimental_*
    1. 通常意味着：
      1. 行为可能变化。
      2. 文档不稳定。
      3. 不适合作为长期稳定配置。
    2. 除非你明确知道自己在试什么，否则不建议作为主配置长期使用。
  3. 很多 [features]
    1. 如果你不清楚具体开关作用，不建议随意打开。

一份实用的起步版配置

model = "gpt-5.4"
model_reasoning_effort = "high"
review_model = "gpt-5.4"

approval_policy = "on-request"
sandbox_mode = "workspace-write"

web_search = "cached"
service_tier = "default"

[sandbox_workspace_write]
network_access = false

[profiles.fast]
model = "gpt-5.4-mini"
model_reasoning_effort = "low"

[profiles.deep]
model = "gpt-5.4"
model_reasoning_effort = "xhigh"

实际建议

如果只想抓最关键的部分，优先看这几个：

  1. model
  2. model_reasoning_effort
  3. review_model
  4. approval_policy
  5. sandbox_mode
  6. [sandbox_workspace_write].network_access
  7. profiles

配置文件优化

"节省 token 但体验还比较稳”的配置

  1. disable_on_external_context = true
    1. 线程如果用了外部上下文，比如 MCP 工具调用、web search、tool search，就不进入记忆生成。适合把“查资料/跑工具”的会
    2. 话排除掉，减少噪声记忆。默认是 false。
  2. min_rollout_idle_hours = 12
    1. 一个线程至少空闲 12 小时后，才会被考虑生成记忆。数值越大，生成越少、越保守。默认是 6。
  3. min_rate_limit_remaining_percent = 40
    1. 只有当 Codex 的剩余额度还高于 40% 时，才开始记忆生成。数值越大，越不容易在忙的时候触发后台记忆。默认是 25。
  4. max_rollouts_per_startup = 8
    1. 每次启动时，最多处理 8 个 rollout 候选做记忆。它限制的是“这次启动做多少”，不是永久总量。默认是 16。
  5. max_raw_memories_for_consolidation = 128
    1. 做全局 consolidation 时，只保留最近 128 条 raw memories 作为输入。数值越小，越省，但长期回忆能力也会更弱。
    2. 默认是 256。
[features]
memories = true
[memories]
use_memories = true
generate_memories = true
min_rollout_idle_hours = 12
min_rate_limit_remaining_percent = 40
max_rollouts_per_startup = 8
max_raw_memories_for_consolidation = 128
disable_on_external_context

官方文档

  1. Config basics (https://developers.openai.com/codex/config-basic)
  2. Memories (https://developers.openai.com/codex/memories)
  3. Config reference (https://developers.openai.com/codex/config-reference)

Codex CLI 会话的中断和恢复

Codex CLI 在被强制中断（如 Ctrl+C）时，确实不会在终端回显 Session ID。这并非故障，而是因为进程被立即终止，来不及打印"善后信息"。

为什么有时候不显示？

  1. 正常退出（/exit）
    1. CLI 会完整执行退出流程，通常会打印 Session ID 或提示"Session saved"。
  2. 强制中断（Ctrl+C）
    1. 进程收到 SIGINT 信号后立即终止，来不及打印任何输出。此时 Session 虽然已保存，但 ID 被"吞"掉了。

如何找回被“吞”掉的 Session？

即使没看到 ID，Session 文件依然保存在本地，你可以通过以下方式找回：

  1. 查看最近的文件（最快）
    1. 会话文件按时间戳命名，直接查看最新的文件即可：
    2. ls -lt ~/.codex/sessions/$(date +%Y/%m/%d)/
    3. 文件名格式为 rollout-2026-04-22T10-30-00-xxx.jsonl，其中的 xxx部分通常包含 Session ID。
  2. 使用交互式选择器
    1. 运行以下命令，Codex 会列出所有可恢复的会话（包含 ID 和路径）：
    2. codex resume
  3. 直接恢复最近一次
    1. 如果你只是想继续刚才的工作，直接使用 --last参数，无需手动找 ID：
    2. codex resume --last
What do you think?
0 Reactions
Pick a reaction
codex ,  session
Back | Home