跳转至

高级配置

GPT-5 prompt 贡献

OpenClaw 会向匹配的、由 OpenClaw 组装的 GPT-5 系列 prompt 添加一项共享的 GPT-5 prompt 贡献。下方的 OpenAI 插件设置控制 OpenAI 系列路由上的友好风格。较旧的 GPT-4.x 模型 id 不匹配。

原生 Codex 应用服务器 harness 不会通过开发者指令接收 persona/工具纪律行为契约或友好交互风格覆盖层;原生 Codex 保留 Codex 自有的 base、model 和 project-doc 行为,并且 OpenClaw 会为原生线程禁用 Codex 的内置 personality,以便 agent 工作区中的 personality 文件保持权威。OpenClaw 仅向原生 Codex 线程贡献运行时上下文:channel 投递、OpenClaw 动态工具、ACP 委派、工作区上下文和 OpenClaw skills。来自同一贡献的 heartbeat 引导文本是唯一的例外:原生 Codex 的 heartbeat 轮次确实会收到它,但它是作为专门的协作指令注入的,而不是通过共享的 prompt 贡献钩子。

GPT-5 贡献会为匹配的、由 OpenClaw 组装的 prompt 添加一个带标签的行为契约,涵盖 persona 持久化、执行安全、工具纪律、输出形态、完成检查和验证。特定于 channel 的回复和静默消息行为仍保留在共享的 OpenClaw 系统 prompt 和出站投递策略中。友好交互风格层是独立且可配置的。

值 效果
"friendly"(默认) 启用友好交互风格层
"on" "friendly" 的别名
"off" 仅禁用友好风格层
{
  plugins: {
    entries: {
      openai: {
        config: { personality: "friendly" },
      },
    },
  },
}
openclaw config set plugins.entries.openai.config.personality off

Tip

值在运行时不区分大小写,因此 "Off" 和 "off" 都会禁用友好风格层。

Note

已废弃的 agents.defaults.promptOverlays 键不再被读取;配置校验会拒绝它,并且当 plugins.entries.openai.config.personality 未设置时,openclaw doctor --fix 会将其 personality 值迁移到该键下。

高级配置

下方的 transport 和 serviceTier 示例是作者编写的 embedded-provider 请求设置,因此本来符合条件的 auto 路由会保留在 OpenClaw 上,而不会隐式选择 Codex。有效的 fastMode / fast_mode 值和有效的 cutoff 键是类型化的 agent-runtime 控件,不会选择任何运行时。因此,特定于运行时的示例会显式固定 agentRuntime.id。原生 Codex 应用服务器 harness 拥有自己的 transport 和请求设置。因此,即使显式设置了 agentRuntime.id: "codex",作者编写的 embedded-provider 设置仍然可以选择声明的 OpenClaw 回退;请参阅 运行时选择。

Transport(WebSocket 与 SSE)

直接 API key 请求默认使用 SSE。当你想在符合条件的官方 OpenAI endpoint 上使用 Responses WebSocket 模式时,请设置 params.transport。

值 行为
"sse"(默认) 通过 SSE 流式传输每个请求
"auto" 优先使用会话缓存的 WebSocket,并在分发前提供 SSE 回退
"websocket-cached" 显式使用会话缓存的 WebSocket 路径,并具有相同的分发前 SSE 回退
"websocket" 为请求使用临时 WebSocket,并在分发前提供 SSE 回退

缓存模式会为每个会话保留一个符合条件的连接。当先前的请求和响应仍与当前历史匹配时,OpenClaw 只发送新的输入,并通过 previous_response_id 引用先前的响应。否则,它会发送完整历史而不带该引用。

在请求分发之前发生的设置或握手失败会回退到 SSE;不会先重试或重新连接。分发之后,结果未知的失败仍然无法安全重放,并会保持 fail-closed(故障时关闭)状态。显式的服务器拒绝 —— previous_response_not_found、websocket_connection_limit_reached,以及 Zero Data Retention 对 previous_response_id 的 unsupported_parameter 拒绝 —— 是安全异常:OpenClaw 会关闭失败的 socket,并通过 SSE 使用完整历史重试该轮次一次,且不包含被拒绝的 previous_response_id。

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          agentRuntime: { id: "openclaw" },
          params: { transport: "auto" },
        },
      },
    },
  },
}

相关 OpenAI 文档: - Responses API WebSocket 模式 - 流式 API 响应(SSE)

快速模式
OpenClaw 为 `openai/*` 提供了一个共享的快速模式开关:

- **聊天/UI:** `/fast status|auto|on|off`
- **配置:** `agents.defaults.models["<provider>/<model>"].params.fastMode`

有效的 `params.fastMode` / `params.fast_mode` 值和有效的 cutoff 键是类型化的运行时控件。它们不计为作者编写的 provider 请求参数,也不会选择 OpenClaw 或 Codex。下面的示例固定使用 embedded OpenClaw,因为它描述的是直接的 provider 请求。

在 embedded 运行时上启用后,OpenClaw 会将快速模式映射到 OpenAI API 的 Fast mode(原 Priority processing),并发送 `service_tier = "priority"`。快速模式不会改写 `reasoning` 或 `text.verbosity`。`fastMode: "auto"` 会以快速模式启动新的模型调用,直到 auto cutoff;之后启动的重试、回退、工具结果或继续调用将不再使用快速模式。cutoff 默认值为 60 秒;在活动模型上设置 `params.fastAutoOnSeconds` 可更改它。

json5 { agents: { defaults: { models: { "openai/gpt-5.5": { agentRuntime: { id: "openclaw" }, params: { fastMode: "auto", fastAutoOnSeconds: 30 }, }, }, }, }, }

!!! note

    完整的优先级顺序为:内联消息、已存储会话、按智能体默认值、全局默认值、按模型 `params.fastMode`,最后为关闭。`/fast default` 仅清除会话层。`/status` 报告的是已解析的 OpenClaw 策略和运行时,而非上游服务实际遵循或返回的服务层级。另请参阅 [思考级别](../../tools/thinking.md#fast-mode-%2Ffast) 和 [Codex 工具链](../../plugins/codex-harness/commands.md#shared-fast-mode-and-codex-fast-mode)。

    快速模式(Fast mode)属于溢价且因模型而异。GPT-5.6 Sol API 快速模式目前按标准 Token 定价的 2× 计费,长上下文倍率会叠加,详见 [上下文窗口默认值与长上下文选择启用](setup.md#context-window-defaults-and-long-context-opt-in)。ChatGPT/Codex 积分快速模式是一个独立的计费体系:GPT-5.6 和 GPT-5.5 目前消耗 2.5× 标准积分,而使用 API 密钥的 Codex 运行则采用 API Token 定价。另请参阅 [快速模式](https://openai.com/api-priority-processing/)、[API 定价](https://developers.openai.com/api/docs/pricing) 和 [Codex 速度](https://learn.chatgpt.com/docs/agent-configuration/speed)。
OpenAI API 快速模式与 service_tier
OpenAI 现在将这一 API 产品称为 Fast mode;它以前称为 Priority processing。OpenClaw 发送传输值 `service_tier = "priority"`。请在嵌入式 OpenClaw 运行时上为每个模型设置显式层级:

```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          agentRuntime: { id: "openclaw" },
          params: { serviceTier: "priority" },
        },
      },
    },
  },
}
```

支持的取值:`auto`、`default`、`flex`、`priority`。

Warning

params.serviceTier 是作者配置的嵌入式提供程序设置,而非原生 Codex 应用服务器配置。它仅由嵌入式运行时转发给原生 OpenAI 端点(api.openai.com)和原生 ChatGPT 端点(chatgpt.com/backend-api)。如果通过代理路由任一提供程序,OpenClaw 不会改动 service_tier。请使用 plugins.entries.codex.config.appServer.serviceTier 单独配置原生工具链;共享的 Fast-mode 运行控制可以覆盖该值。

服务端压缩(Responses API)
对于支持存储的直接 OpenAI Responses 模型(`openai/*` 解析到 `api.openai.com`),OpenAI 插件的 OpenClaw 流包装器会自动启用服务端压缩(server-side compaction):

- 强制 `store: true`(除非模型兼容性将 `supportsStore` 设置为 `false`)
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`:为 `contextWindow` 的 70%(不可用时为 `80000`)

相同的已解析路由和有效阈值会控制客户端预检行为,因此 OpenClaw 不会延迟本地压缩,除非传输层会注入 `context_management`。ChatGPT OAuth、自定义代理以及 `compat.supportsStore: false` 的路由不具备存储能力,因此会忽略这些服务端压缩控制。这适用于内置 OpenClaw 运行时路径,以及嵌入式运行使用的 OpenAI 提供程序钩子。原生 Codex 应用服务器工具链通过 Codex 管理自身上下文,不受此设置影响。

OpenAI 会将压缩后的状态作为加密的 `compaction` 输出项发出。请将该输出项视为不透明数据。对于无状态延续,请携带最新的输出项,并丢弃它所替换的较早输入前缀。OpenClaw 会自动执行此操作:它仅针对匹配的路由、会话和认证身份持久化并重放该输出项,跨 worker 转录提交保留它,并将其从用户可见的历史记录和诊断信息中过滤掉。切勿显示或记录加密内容。

适用于支持存储的端点(如 Azure OpenAI Responses)。将此设置为 true 不会覆盖端点或 supportsStore 能力:

json5 { agents: { defaults: { models: { "azure-openai-responses/gpt-5.5": { params: { responsesServerCompaction: true }, }, }, }, }, }

json5 { agents: { defaults: { models: { "openai/gpt-5.5": { params: { responsesServerCompaction: true, responsesCompactThreshold: 120000, }, }, }, }, }, }

json5 { agents: { defaults: { models: { "openai/gpt-5.5": { params: { responsesServerCompaction: false }, }, }, }, }, }

Note

responsesServerCompaction 仅控制 context_management 的注入。公共 OpenAI Responses API 默认还会使用 /responses/compact 进行预算触发的压缩。设置 params.responsesCompactEndpoint: false 可禁用这个独立的端点。提供程序确认的溢出和端点故障会使用客户端摘要处理。手动压缩保持其现有行为,除非通过 params.responsesCompactEndpoint: true 显式启用此端点。

直连 OpenAI Responses 模型仍会强制设置 store: true,除非 compat 设置了 supportsStore: false。

strict-agentic GPT 模式
对于通过 OpenClaw 嵌入式运行时运行的 `openai` 提供商的 GPT-5 系列模型,OpenClaw 默认已采用一种更严格的执行契约,称为 `strict-agentic`。只要解析后的提供商为 `openai` 且模型 id 匹配 GPT-5 系列,它就会自动启用,除非配置明确选择退出:

```json5
{
  agents: {
    defaults: {
      embeddedAgent: { executionContract: "default" },
    },
  },
}
```

在受支持的通道上显式设置 `"strict-agentic"` 不会产生影响(它已经是默认值),在不受支持的提供商/模型组合上也不会生效。

启用 `strict-agentic` 后,OpenClaw 会:
- 除非 `tools.updatePlan` 将其禁用,否则在实质性工作时使 `progress_card` 可用
- 使用可见答案的续写,对结构上为空或仅包含推理的回合进行重试
- 当所选 harness 提供显式计划事件时,使用这些显式 harness 计划事件

OpenClaw 不会通过分类助手文本来判断某个回合是计划、进度更新还是最终答案。

Note

该契约完全位于 OpenClaw 的嵌入式 agent runner 中。它不适用于原生 Codex app-server harness,后者会自行管理其回合和计划行为;对于原生 Codex 运行,harness 选择比执行契约设置更重要。

原生与 OpenAI 兼容路由

OpenClaw 对直连 OpenAI、Codex 和 Azure OpenAI 端点的处理方式,与通用 OpenAI 兼容 /v1 代理不同:

原生路由(openai/*、Azure OpenAI): - 仅对支持 OpenAI none effort 的模型保留 reasoning: { effort: "none" } - 对于拒绝 reasoning.effort: "none" 的模型或代理,省略已禁用的 reasoning - 默认将工具 schema 设为严格模式 - 仅在已验证的原生主机上附加隐藏归属头(Azure OpenAI 不会获得这些头,尽管它是原生路由) - 保留 OpenAI 专用的请求整形(service_tier、store、reasoning-compat、prompt-cache 提示)

代理/兼容路由: - 使用更宽松的 compat 行为 - 从非原生 openai-completions 负载中移除 Completions store - 接受用于 OpenAI 兼容 Completions 代理的高级 params.extra_body/params.extraBody 透传 JSON - 接受用于 vLLM 等 OpenAI 兼容 Completions 代理的 params.chat_template_kwargs - 不强制使用严格工具 schema 或仅限原生的头

如果可用的工具 schema 与请求的严格模式不兼容,请求将使用 strict: false。调试日志会在 openai-transport 下报告降级情况,并附带不兼容工具的有界样本。内置和托管 Responses 请求对相同模型和 schema 共享去重抑制。

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