配置

Codex 运行框架配置映射以及每个设置所控制的轮次级行为。属于 Codex 运行框架 指南的一部分；各部分迁移位置 列出所有部分。

配置¶

对于订阅优先/API 密钥备份顺序，优先使用 auth.order.openai。 现有的旧版 Codex 身份验证配置文件 ID 和旧版 Codex 身份验证顺序是 仅限 doctor 的旧版状态；不要写入新的旧版 Codex GPT 引用。

{
  auth: {
    order: {
      openai: ["openai:user@example.com", "openai:api-key-backup"],
    },
  },
}

对于 Codex 兼容的有效路由，上述两个配置文件仍然是同一 Codex 运行的候选项。 配置文件顺序选择凭据，而不是运行时。 更改身份验证顺序不会使自定义、Completions、HTTP 或 请求覆盖路由变为 Codex 兼容。有效的模型范围 Fast-mode 和 cutoff 控制是运行时控制，而不是请求覆盖。

受限轮次与 Ring zero¶

OpenClaw 按轮次应用 Codex 限制，而不是作为永久会话模式。 因此，现有会话可以运行一个受限轮次，并在下一个非受限轮次返回其 正常 Codex 线程。当限制是临时性的时，OpenClaw 会保留正常线程绑定，并在必要时使用临时 受限线程。

普通的 策略受限轮次 发生在显式 OpenClaw 工具 策略无法安全映射到 Codex 原生工具表面时。常见 触发条件包括：

• 有限的 tools.allow 列表或内部每次运行允许列表
• disableTools 或拒绝所有工具的发送者/组策略
• 包含通配符、工具组、未知名称，或不在 Codex 运行框架已审计安全拒绝集合中的名称的 tools.deny 条目
• 具有上述任一限制的适用代理、提供商、组、发送者、沙箱、子代理、继承、 计划或运行时工具策略

仅默认工具配置文件收窄不会触发此模式。仅包含已审计的 OpenClaw 自有工具的拒绝列表 也可以保留在正常原生表面上；运行框架会执行这些拒绝，而不会禁用无关的 Codex 功能。有关通用运行框架契约，请参阅 原生工具策略执行； 有关当前 Codex 规则，请参阅 Codex 运行框架参考。

对于普通策略受限轮次，OpenClaw 会禁用 Codex 原生 Code Mode，移除环境选择，禁用并验证继承的和 原生配置的 MCP 服务器，并禁用原生 hook 中继。通过有效策略的静态配置 MCP 工具会移动到 OpenClaw 的动态表面，用于 该轮次。其他 OpenClaw 动态工具使用相同策略。有界工作区 AGENTS.md 快照仍会作为线程级开发者指令到达模型，因为 项目指令是上下文，而不是工具权限。

Ring zero 更强且独立。它是主机拥有的 OpenClaw 系统 代理，用于设置和修复操作。主机使用单个 openclaw 工具激活它；普通代理配置不能将聊天加入 Ring zero。 Ring zero 轮次仅保留该主机范围工具，用主机编写的设置指令替换环境 Codex 指令，禁用原生工具和 MCP 服务器，并抑制工作区项目文档，包括 AGENTS.md 开发者指令载体。

其他狭窄的内部模式也会抑制项目文档：轻量引导轮次、仅消息源回复以及禁用工具的内部轮次。它们与策略受限轮次共享一些隔离设置，但不是 ring zero 的同义词。

项目指令¶

Codex 通过原生项目文档发现机制加载 AGENTS.md 文件。对于普通 app-server 线程，OpenClaw 将 Codex 的根目录到工作目录的聚合预算从上游默认的 32 KiB 提高到有界的 128 KiB，以免后续范围化指令被静默截断。普通对话的工具策略限制会保留该预算，因为项目指令是上下文，而不是工具权限。其隔离的原生环境无法读取工作区文件，因此 OpenClaw 提供有界的工作区 AGENTS.md 快照，作为线程级开发者指令。显式编写的原生 project_doc_max_bytes 设置会覆盖普通线程的 128 KiB 回退值；Codex 物化的 32 KiB 默认值不会。轻量、ring-zero、仅消息以及禁用工具的内部轮次会将原生项目文档预算改为零。

继承的代理工作区 AGENTS.md 快照在其原生线程中保持固定，即使文件被编辑、清空或删除也是如此。请启动新会话以加载当前工作区指令。

此字节预算独立于通过 agents.defaults.bootstrapMaxChars 和 agents.defaults.bootstrapTotalMaxChars 配置的基于字符的工作区引导限制。

/context 将原生项目文档报告为未验证，因为 app-server 会公开其源路径，但不会公开用于判断某个单独文件是否已完整加载或被截断的保留字节数。

压缩¶

不要在 Codex 支持的代理上设置 compaction.model 或 compaction.provider。Codex 通过其原生 app-server 线程状态执行压缩，因此 OpenClaw 在运行时忽略这些本地摘要器覆盖，并且当代理使用 Codex 时，openclaw doctor --fix 会移除它们。

编写的 models.providers.*.models[].contextTokens 上限会作为 model_context_window 转发到 Codex 线程启动和恢复。Codex 会将该值限制在模型原生最大值内，并基于受限窗口推导自动压缩。当模型条目没有编写上限时，OpenClaw 不发送覆盖。

Lossless 仍可作为上下文引擎，用于 Codex 轮次周围的组装、摄取和维护，通过 plugins.slots.contextEngine: "lossless-claw" 和 plugins.entries.lossless-claw.config.summaryModel 配置，而不是通过 agents.defaults.compaction.provider。当 Codex 是活动运行时，openclaw doctor --fix 会将旧的 compaction.provider: "lossless-claw" 形状迁移到 Lossless 上下文引擎插槽，但原生 Codex 仍拥有压缩。原生 app-server 框架支持需要提示前组装的上下文引擎；通用 CLI 后端（包括 codex-cli）不提供该主机能力。

新的 Codex 线程（包括普通 Fork conversation 会话）会在有界的连续性窗口内接收最近保存的历史。适合该窗口的对话文本和摘要会在没有单独逐消息截断的情况下保留；更长的历史会保留其最新尾部。工具负载和恢复的附件保留其自身限制。

对于 Codex 支持的代理，/compact 会在绑定线程上启动原生 Codex app-server 压缩，并等待其最终结果。共享的 agents.defaults.compaction.timeoutSeconds 预算适用；超时后，OpenClaw 会要求 Codex 中断原生轮次，并保留每线程围栏，直到确认终止。它绝不会回退到上下文引擎或公共 OpenAI 摘要器。如果原生 Codex 线程绑定缺失或过期，该命令会失败关闭，而不是静默切换压缩后端。SIWC 支持的原生线程不能使用手动 /compact。轮内自动压缩仍然可用；当需要全新上下文时，请继续对话或启动新会话。

取消会阻止尚未提交的原生请求，包括过载重试。提交后，OpenClaw 会保持线程占用，直到确认原生完成、中断或安全退役。已停止的轮次会关闭可见的压缩进度，而不会将未完成的压缩标记为成功，也不会使先前观察到的原生工作具备重放资格。

直接 API 长上下文¶

Codex 订阅和直接 OpenAI API 流量是独立的契约。实时 ChatGPT/Codex 目录通常公开 272000 token 模型窗口，而 OpenAI 文档中 GPT-5.5 和 GPT-5.6 的 Platform API 窗口为 1050000 token，最大输出为 128000。两种运行时转换都使用相同的安全算术：

1050000 total - 128000 maximum output = 922000 safe active input
automatic compaction threshold = 700000 active tokens

原生 Codex 转换不是 Responses 参数集。Codex 拥有原生线程的上下文和压缩，因此不要向 Codex 支持的模型添加 responsesServerCompaction 或 responsesCompactThreshold。

从与已安装 Codex 版本兼容的完整 Codex 模型目录开始。对于确切的 gpt-5.6-sol 条目，保留描述符的其余部分并设置：

{
  "context_window": 922000,
  "max_context_window": 922000,
  "auto_compact_token_limit": 700000
}

Codex 会对 922000 目录值应用其正常的 95% 有效窗口预留，因此它恰好报告 875900 可用 token。在 700000 处压缩会在该有效保护之前留下 175900 token，并在提供商安全输入允许值之前留下 222000。这种更大的余量是有意为之：Codex 在添加下一条用户消息和上下文更新之前会检查已记录的上下文，因此阈值必须覆盖一个大型传入轮次，以及工具、指令、序列化和压缩轮次本身。

对于独立的 Codex CLI 或 Desktop 使用，命令认证自定义提供商可以从系统钥匙串或密钥管理器读取 API 密钥，同时普通 ChatGPT 登录仍可用于连接器：

model = "gpt-5.6-sol"
model_provider = "openai_api_direct"
model_context_window = 922000
model_auto_compact_token_limit = 700000
model_auto_compact_token_limit_scope = "total"
model_catalog_json = "/absolute/path/to/models-api-1m.json"

[model_providers.openai_api_direct]
name = "OpenAI API direct"
base_url = "https://api.openai.com/v1"
wire_api = "responses"
requires_openai_auth = false

[model_providers.openai_api_direct.auth]
command = "/absolute/path/to/read-openai-inference-key"
timeout_ms = 5000
refresh_interval_ms = 300000

认证辅助程序必须仅将密钥打印到 stdout。不要将其写入 TOML。

对于 OpenClaw Codex app-server 测试框架，保留默认的 agent 作用域 Codex home，并让 OpenClaw 注入一个 openai API-key profile。通过常规的 OpenAI API-key 认证流程创建该 profile，并将其实际 id 放在 auth.order.openai 的第一位，并将模型目录和上下文限制作为原生 Codex app-server 参数传入：

{
  auth: {
    order: {
      openai: ["openai:api-key"],
    },
  },
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          appServer: {
            args: [
              "app-server",
              "--listen",
              "stdio://",
              "-c",
              'model_catalog_json="/absolute/path/to/models-api-1m.json"',
              "-c",
              "model_context_window=922000",
              "-c",
              "model_auto_compact_token_limit=700000",
              "-c",
              "model_auto_compact_token_limit_scope=total",
            ],
          },
        },
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.6-sol" },
      models: {
        "openai/gpt-5.6-sol": {
          agentRuntime: { id: "codex" },
          params: { fastMode: true },
        },
      },
    },
  },
}

将 openai:api-key 替换为实际的 API-key profile id。agent 作用域的 app-server 只会接收该准备好的密钥；操作员的原生 ~/.codex ChatGPT 登录、插件、连接器和线程存储保持不变。对于此路由，请使用上面注入的 agent 作用域 API-key 路径，而不是依赖 homeScope: "user" 来提供预期凭证。

模型目录、model_context_window、total 作用域的自动压缩限制、精确的 openai/gpt-5.6-sol 路由以及 API-key profile 顺序构成一个配置单元。请一起应用它们。只有当它们的模型引用或 agent 配置可区分时，OpenClaw 才能同时保留嵌入式和原生长上下文选项；一个 model 条目不能同时承载两种 runtime 拥有的压缩策略。

更改模型目录或 app-server 参数后，重启 Gateway 和原生 Codex app-server，然后开始一个新聊天。当现有会话存在 model 或 runtime 覆盖时，运行 /model default -s。现有原生线程会保留其记录的 provider 和 model 设置。使用 /status 和 /codex status 验证 runtime，然后在开始长会话之前发送一个无害的直接 API 回合。

一个进程拥有的隔离 Gateway 和 app-server 运行验证了该精确的 openai/gpt-5.6-sol API-key 配置。Codex 报告有效窗口为 875900。活动上下文从 197032 增长到 377386、561957 和 750745 tokens，且未进行手动压缩；下一个小回合触发了自动压缩，压缩到 75980 个活动 tokens，压缩后最小快照为 68375。压缩耗时 2810 ms，并持久化了一个计数为 1 的值。一个持久标记在压缩和重启后仍然存在，一个确定性的长响应产生了 5442 个输出 tokens，并且 OpenClaw 在每次调用中都向 Codex app-server 发送了 tier priority。该请求证据不能证明每次调用由哪个上游 tier 处理。完整测试套件耗时 401.37 秒。这些计时是观察值，不是服务级别保证。

本指南的其余部分涵盖部署形态和 fail-closed 路由、guardian 审批策略 以及原生 Codex 插件和 Computer Use。如需完整的选项列表、默认值、枚举、发现、环境隔离、超时以及 app-server 传输字段，请参阅Codex harness 参考。