——
OpenClaw GPT-5.4 智能体运行时升级：6大关键改进与配置指南
一句话总结：本次更新让 GPT-5 系列模型在 OpenClaw 中默认获得企业级执行稳定性，彻底消除”规划后卡死”和”静默失败”两大顽疾。
如果你正在使用 OpenClaw 构建基于 GPT-5 或 OpenAI Codex 的 AI Agent 应用，可能会遇到这样的困扰：Agent 完成规划后突然停止响应，或者任务失败时没有任何明确提示。本文将详细解读 OpenClaw 最新合并的 #65219 提交如何解决这些问题，并提供完整的配置实践指南。
—
一、背景：GPT-5.4 兼容性完成的最后障碍
OpenClaw 团队为 GPT-5.4 版本设定了严格的兼容性标准（parity completion gate），其中两项核心准则长期未能完全满足：
• 准则：准则 1；问题描述：规划阶段后不允许出现执行停滞；影响：用户配置不当会导致 Agent 仅重试1次规划后放弃
• 准则：准则 4；问题描述：重放/活性失败必须显式报告，而非静默消失；影响：严格智能体模式的阻塞退出缺乏状态标记
本次更新通过引入 自动执行合约解析 和 显式终端状态标记 两大机制，彻底解决了上述问题。
—
二、核心更新详解
2.1 自动激活 strict-agentic 执行合约
#### 问题根源
此前，strict-agentic（严格智能体）执行合约需要用户显式配置 agents.defaults.embeddedPi.executionContract 才能启用。大量 OpenAI 和 OpenAI-Codex 用户因未配置该参数，仅获得1次规划重试机会，随后便落入普通完成路径，导致任务停滞。
#### 解决方案：智能合约解析器
OpenClaw 新增了 resolveEffectiveExecutionContract 函数，位于 src/agents/execution-contract.ts：
// 执行合约解析逻辑（简化示意）
function resolveEffectiveExecutionContract(config) {
const isSupportedModel =
config.provider === 'openai' || config.provider === 'openai-codex'
&& config.model.startsWith('gpt-5');
if (isSupportedModel) {
// GPT-5 系列 + 未指定或显式指定 strict-agentic → 启用严格模式
if (!config.executionContract || config.executionContract === 'strict-agentic') {
return 'strict-agentic';
}
// 显式指定 default → 尊重用户选择（退出机制）
if (config.executionContract === 'default') {
return 'default';
}
}
// 非支持模型一律使用 default
return 'default';
}
#### 关键行为变更
• 场景：GPT-5 + OpenAI + 未配置；之前行为：仅1次规划重试，然后停滞；现在行为：自动启用 strict-agentic，2次重试 + 阻塞状态处理
• 场景：GPT-5 + OpenAI + 显式 strict-agentic；之前行为：严格模式生效；现在行为：保持不变
• 场景：GPT-5 + OpenAI + 显式 default；之前行为：—；现在行为：尊重选择，使用传统行为
• 场景：其他模型/提供商；之前行为：取决于配置；现在行为：强制使用 default，避免不兼容
> 配置提示：如需显式退出自动严格模式，请在配置中设置：
>
> agents:
> defaults:
> embeddedPi:
> executionContract: "default" # 显式退出
> —
2.2 阻塞退出的显式状态标记
#### 问题根源
在 src/agents/pi-embedded-runner/run.ts 的第1615行，严格智能体模式的阻塞退出路径未设置 replayInvalid 和 livenessState，导致下游观测系统（生命周期日志、ACP 桥接、遥测）无法识别该终端状态。
#### 修复方案
// run.ts:1615 附近 - 修复后的阻塞退出处理
if (isBlockedExit) {
// 新增：显式设置终端生命周期元数据
setTerminalLifecycleMeta({
replayInvalid: resolveReplayInvalidForAttempt(attemptContext),
livenessState: "abandoned", // 明确标记为放弃状态
exitReason: "strict-agentic-blocked",
timestamp: Date.now()
});
// 原有逻辑...
return createBlockedExitResult();
}
#### 状态标记的一致性
修复后，所有终端返回路径统一通过 setTerminalLifecycleMeta 设置元数据：
• 退出类型：正常完成；livenessState："completed"；replayInvalid：false；观测可见性：✅ 完整
• 退出类型：异常终止；livenessState："failed"；replayInvalid：true；观测可见性：✅ 完整
• 退出类型：超时取消；livenessState："timeout"；replayInvalid：true；观测可见性：✅ 完整
• 退出类型：严格智能体阻塞（修复前）；livenessState：未设置；replayInvalid：未设置；观测可见性：❌ 静默
• 退出类型：严格智能体阻塞（修复后）；livenessState："abandoned"；replayInvalid：动态解析；观测可见性：✅ 完整
—
三、回归测试覆盖
本次更新新增了 6 项回归测试，确保行为稳定性：
本地验证命令（122/122 通过）
pnpm test \
src/agents/openclaw-tools.update-plan.test.ts \
src/agents/pi-embedded-runner/run.incomplete-turn.test.ts \
src/agents/pi-embedded-runner.buildembeddedsandboxinfo.test.ts \
src/agents/system-prompt.test.ts \
src/agents/openclaw-tools.sessions.test.ts \
src/agents/pi-embedded-runner/run.overflow-compaction.test.ts
测试用例清单
• 测试名称：auto-enables update_plan for unconfigured GPT-5 openai runs；验证目标：未配置时自动启用规划更新
• 测试名称：respects explicit default contract opt-out on GPT-5 runs；验证目标：显式 default 配置被尊重
• 测试名称：does not auto-enable update_plan for non-openai providers；验证目标：非 OpenAI 提供商不触发自动启用
• 测试名称：emits explicit replayInvalid + abandoned liveness state；验证目标：阻塞退出状态显式化
• 测试名称：auto-activates strict-agentic for unconfigured GPT-5 openai runs；验证目标：核心自动激活逻辑
• 测试名称：respects explicit default contract opt-out on GPT-5 openai runs；验证目标：重复验证显式退出机制
—
四、配置实践指南
4.1 推荐配置（大多数用户）
openclaw.config.yaml
agents:
defaults:
embeddedPi:
# 留空或省略 - 让 OpenClaw 自动为 GPT-5 选择最优模式
# executionContract: ~
# 其他推荐配置
maxPlanningRetries: 2
enableLivenessProbe: true
4.2 显式控制配置（高级场景）
场景A：强制使用传统行为（如与旧系统集成）
agents:
defaults:
embeddedPi:
executionContract: "default"
maxPlanningRetries: 1 # 传统模式仅1次重试
场景B：显式启用严格模式（明确意图）
agents:
defaults:
embeddedPi:
executionContract: "strict-agentic"
blockedExitHandler: "notify-and-wait" # 自定义阻塞处理
4.3 运行时诊断
启用详细日志以观察合约解析过程：
DEBUG=openclaw:agents:execution-contract pnpm run agent:execute --model gpt-5-turbo
预期输出片段：
[DEBUG] Resolving effective execution contract...
[DEBUG] Provider: openai, Model: gpt-5-turbo-2024-xx
[DEBUG] User config: undefined → Auto-selected: strict-agentic
[DEBUG] Strict-agentic active: 2 retries, blocked-state handling enabled
—
五、常见问题（FAQ）
Q1：升级后我的 GPT-4 应用会受影响吗？
不会。自动激活机制仅针对 gpt-5 系列模型。GPT-4 及其他模型无论配置如何，均使用 default 执行合约，行为保持不变。
Q2：”abandoned” 状态与 “failed” 有什么区别？
• 状态：failed；含义：执行过程中发生可识别错误；典型场景：工具调用异常、代码执行错误
• 状态：abandoned；含义：因策略限制主动放弃继续；典型场景：严格智能体模式下规划重试耗尽、人为阻塞
在监控告警中，建议对 abandoned 状态进行单独处理，通常需要人工介入审查规划质量。
Q3：如何验证 strict-agentic 是否已激活？
三种验证方式：
1. 日志检查：查找 Strict-agentic active 调试日志
2. 行为观察：GPT-5 任务应出现2次规划重试，而非1次
3. 状态查询：通过 ACP 桥接检查 executionContract 字段返回值
通过 CLI 验证当前会话的生效配置
openclaw agent:inspect --session-id --field executionContext.effectiveContract
Q4：阻塞退出后如何恢复任务？
当前实现中，严格智能体模式的阻塞退出是终端状态，不支持自动恢复。建议：
1. 检查生命周期日志中的 planHistory 分析失败原因
2. 优化系统提示词或工具描述后重新提交任务
3. 如需人工介入流程，可配置 blockedExitHandler: "escalate"
Q5：此更新与 #64679 的关系？
本次提交包含对 #64679 中 loop-6 评审意见 的后续处理，主要涉及错误返回格式的统一。核心功能已在当前提交中完整实现。
—
六、总结与下一步
本次 OpenClaw GPT-5.4 运行时更新 带来了两项关键改进：
1. 零配置优化：GPT-5 用户无需任何改动即可获得企业级执行稳定性
2. 全链路可观测：所有终端状态统一显式标记，消除监控盲区
建议行动
• 优先级：P0；行动项：升级至包含 #65219 的 OpenClaw 版本；时间：立即
• 优先级：P1；行动项：审查现有 GPT-5 应用的监控告警规则，增加 abandoned 状态处理；时间：本周
• 优先级：P2；行动项：评估是否需要显式 default 配置以兼容特殊场景；时间：本月
—
相关阅读
—
参考来源
• 来源：本次合并提交；链接：https://github.com/openclaw/openclaw/commit/26945ddb4955686e6bf1da0b4ee8d368723634e8；说明：完整代码变更与测试用例
• 来源：前置 PR #64679；链接：https://github.com/openclaw/openclaw/pull/64679；说明：strict-agentic 合约初始实现
• 来源：关联 Issue #64227；链接：https://github.com/openclaw/openclaw/issues/64227；说明：GPT-5.4 兼容性追踪
• 来源：OpenClaw 官方文档；链接：OpenClaw 文档；说明：执行合约配置参考
—
本文基于 OpenClaw 开源项目公开提交撰写，技术细节以官方文档为准。如有疑问，欢迎通过 GitHub Discussions 参与讨论。
