跳转至

配置

Codex harness 配置映射,以及每个设置所控制的回合级行为。本页是 Codex harness 指南的一部分;各节移动去向 列出了每个章节。

配置

需求 设置项 位置
启用该 harness plugins.entries.codex.enabled: true OpenClaw 配置
隐藏 Codex 原生会话发现 plugins.entries.codex.config.sessionCatalog.enabled: false Codex 插件配置
包含额外的本地 Codex 存储(仅 stdio) plugins.entries.codex.config.sessionCatalog.homes Codex 插件配置
保留一个已列入允许列表的插件安装 在 plugins.allow 中包含 codex OpenClaw 配置
允许符合条件的 OpenAI 回合隐式使用 Codex 确切官方 HTTPS Responses/ChatGPT 路由,没有编写提供方请求覆盖,运行时未设置/为 auto OpenAI 提供方/模型配置
使用 ChatGPT/Codex OAuth 登录 openclaw models auth login --provider openai CLI 认证配置
为 Codex 运行添加 API 密钥备份 在 auth.order.openai 中,将 openai:* API 密钥配置列于订阅认证之后 CLI 认证配置 + OpenClaw 配置
当 Codex 不可用时失败关闭 提供方或模型的 agentRuntime.id: "codex" OpenClaw 模型/提供方配置
使用直接的 OpenAI API 流量 提供方或模型的 agentRuntime.id: "openclaw",配合正常 OpenAI 认证 OpenClaw 模型/提供方配置
调整应用服务器行为 plugins.entries.codex.config.appServer.* Codex 插件配置
启用 Codex 原生插件应用 plugins.entries.codex.config.codexPlugins.* Codex 插件配置
启用 Codex Computer Use plugins.entries.codex.config.computerUse.* 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,或拒绝所有工具的发送者/群组策略
  • tools.deny 条目包含通配符、工具组、未知名称,或不在 Codex harness 经审计的安全拒绝(safe-deny)集中的名称
  • 适用的 agent、提供方、群组、发送者、沙箱、子代理、继承、定时或运行时工具策略包含上述任一种限制

单纯的默认工具配置文件收窄不会触发此模式。仅包含经审计的 OpenClaw 所属工具的拒绝列表也可以停留在正常原生表面上;该 harness 会强制这些拒绝,而不会禁用无关的 Codex 功能。有关通用 harness 契约,请参阅 原生工具策略强制;有关当前 Codex 规则,请参阅 Codex harness 参考。

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

Ring zero 更强,且是独立机制。它是宿主拥有的 OpenClaw 系统代理,用于设置和修复操作。宿主通过唯一的 openclaw 工具激活它;普通代理配置无法将会话置入 ring zero。Ring-zero 回合只保留该宿主作用域工具,将环境中的 Codex 指令替换为宿主编写的设置指令,禁用原生工具和 MCP 服务器,并抑制工作区项目文档,包括承载开发人员指令的 AGENTS.md。

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

项目说明

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

继承的代理工作区 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 token。这个更大的边距是有意为之: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 秒。这些计时是观察值,不是服务级别保证。

Warning

长上下文是刻意采用 opt-in 的。一旦输入超过 272000 tokens, OpenAI 会按 2× 输入和缓存费率以及 1.5× 输出费率对整个请求计费。Fast-mode 定价因模型而异;GPT-5.6 Sol API Fast mode(原 Priority processing)目前比 Standard 再高 2×,因此该方案是短上下文 Standard 输入侧定价的 4×,短上下文 Standard 输出定价的 3×。OpenClaw 当前发送 wire 值 service_tier: "priority"。ChatGPT/Codex-credit Fast mode 是独立的:GPT-5.6 和 GPT-5.5 目前消耗 2.5× Standard credits,而此 API-key Codex 路由使用 API token 定价。API 仍然是访问、实际限制和计费的权威来源。参见 OpenAI 模型限制, Fast mode, API 定价,以及 Codex 速度。

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

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw