目标

快速开始¶

/goal start get CI green for PR 87469 and push the fix
/goal
/goal edit get CI green for PR 87469, push the fix, and update docs
/goal pause waiting for CI
/goal resume
/goal complete pushed and verified
/goal clear

start 是可选的：/goal get CI green for PR 87469 也会创建一个目标。OpenClaw 会将 /goal 后任何不是已知动作词的文本视为新的目标。

start 和 edit 等显式动作会保留目标内的换行、缩进和连续空格。首尾空白会被修剪。

目标的用途¶

当会话有一个具体的成果且需要在多轮对话中持续可见时，请使用目标：

• PR 收尾：修复、验证、自动审查、推送，并打开或更新 PR。
• 调试运行：复现 bug、确定所属模块、打补丁并证明修复有效。
• 文档整理：阅读相关文档、编写新页面、交叉链接，并验证文档构建。
• 维护任务：检查当前状态、做有边界的更改、运行正确的检查并报告更改内容。

目标不是任务队列。当工作应该独立运行、按计划重复、分派为受管理的子工作或作为策略持久存在时，请使用 子代理、cron 任务 或 常设指令。

命令参考¶

/goal 不带参数会打印当前目标摘要：

Goal
Status: active
Objective: get CI green for PR 87469 and push the fix
Tokens used: 12k
Token budget: 12k/50k

Commands: /goal edit <objective>, /goal pause, /goal complete, /goal clear

一个会话同一时间只能有一个目标。在当前目标被清除之前，启动第二个目标会失败并显示 Goal error: goal already exists。

/goal start 不接受 token 预算标志。只有面向模型的 create_goal 工具可以设置预算。

状态¶

• active：会话正在推进该目标。
• paused：操作者暂停了目标，或其运行以错误或超时结束。/goal resume 使其重新变为活动状态。失败的运行会保留目标，并将错误记录为状态备注；发送普通消息不会自动恢复目标。可通过重试恢复的错误不会暂停目标。
• blocked：agent 或操作者报告了实际阻塞。当有新信息或新状态可用时，/goal resume 使其重新变为活动状态。
• budget_limited：达到了配置的 token 预算。/goal resume 会以相同的目标、新的预算窗口重新开始推进。
• usage_limited：保留用于未来的用量限制停止状态。/goal resume 以相同方式重新开始推进。
• complete：目标已达成。已完成的目标是终态的。在开始另一个目标之前，请使用 /goal clear。重复执行完成操作会保留原始的完成时间，即使添加了状态备注也是如此。

/new 和 /reset 会清除当前会话目标，因为它们会刻意启动全新的会话上下文。

Token 预算¶

目标可以有一个可选的、大于零的 token 预算，通过 create_goal 工具的 token_budget 参数设置。预算以目标创建时会话的全新 token 计数为基准。如果目标启动时会话只有过期或未知的 token 快照，OpenClaw 会等待下一个全新快照并将其作为基准，因此在目标存在之前消耗的 token 不会计入该目标。

除非你明确要求预算，否则模型应省略 token_budget。要求每个工具参数都必须提供的传输层可以传入 null 表示无预算。

当用量达到预算时，目标会进入 budget_limited。这不会删除目标或清除目标内容。它告诉操作员和智能体，在目标被恢复或清除之前，该目标不再被积极追求。恢复会从当前新的 Token 计数开始新的预算窗口。

Token 预算是会话目标护栏，而不是计费上限。提供商配额、成本报告和上下文窗口行为仍使用正常的 OpenClaw 用量和模型控制。

模型工具¶

OpenClaw 向智能体框架暴露三个目标工具：

模型不能静默暂停、恢复、清除或替换目标。这些仍是通过 /goal 和重置命令进行的操作员/会话控制，因此智能体可以报告达成或真正的阻塞，而不会悄悄改变目标。

update_goal 只有当目标内容根据完整目标内容验证且没有剩余必需工作时，才应将目标标记为 complete。只有当同一阻塞条件至少连续三个目标轮次再次出现时，才应将目标标记为 blocked，而不是普通困难或缺少打磨。恢复被阻塞的目标会重新开始连续三个轮次的计数。之前的阻塞轮次不计入其中。 即将耗尽的预算不能证明将未完成工作标记为完成。 更新目标状态不会发送聊天回复。智能体仍必须提供用户要求的最终回复。

每个轮次的目标上下文¶

每个具有活动目标的 用户/聊天轮次 都包含以下用户角色上下文行：

Active goal: <objective> — advance; keep active until fully achieved; block only after the same blocker on 3 consecutive turns; after update_goal, provide the requested visible final.

OpenClaw 通过截断长目标内容来保持该行紧凑。暂停、阻塞、预算受限、用量受限和已完成的目标不会被注入，因此操作员停止在目标恢复之前保持生效。

控制 UI¶

使用 Enter、Tab 或点击从命令选择器中选择 目标，然后输入目标内容并选择 开始目标。输入 /goal start 后跟一个空格，或提交没有目标内容的 /goal start，也会打开目标模式。仅发送 /goal，即使在选择器关闭后，也会打开编辑器，而不是向对话中添加命令。空目标内容无法提交。

编辑器显示目标标签和目标内容提示，以便你查看发送将执行的操作。目标内容是字面文本：诸如 clear 之类的词和诸如 /stop 之类的文本在目标模式下不会变成命令。按 Escape 或取消会将目标内容保留为普通聊天草稿。完整粘贴的命令（例如 /goal start Fix the tests）以及显式管理命令（例如 /goal status）保留其文本命令行为。

开始目标会在确认发送之前，一起保存目标、其用户轮次和运行准入。准入失败会保留草稿，并且不会创建目标。失败的旧聊天发送会与新建的目标草稿保持分离，而不是填充其空目标内容。开始和恢复需要内置 OpenClaw 运行时，以及具有可恢复历史的空闲本地会话。它们对原生 Codex 和其他外部运行时不可用，并且不会被排队或引导到另一个运行中。UI 会报告不支持或繁忙的会话，而不是创建非活动目标。

Web 控制 UI 在聊天编辑器上方将目标显示为紧凑胶囊：状态图标、状态标签（例如 Pursuing goal）、截断的目标内容以及实时经过计时器。

活动目标使用绿色目标图标。暂停目标使用中性的暂停图标、正常卡片表面和冻结的经过计时器。被阻塞或受限目标使用琥珀色警告图标和着色卡片；已完成目标使用绿色对勾。状态标签在不依赖颜色的情况下标识每种状态。将鼠标悬停在暂停或阻塞目标的状态标签上或聚焦该标签，以读取其状态说明，包括错误暂停的原因。展开的详细信息也会显示完整说明。

胶囊包含内联控件：

• 铅笔 打开带有当前目标内容的编辑目标编辑器。保存仅更改目标内容。取消会恢复之前的聊天草稿。
• 暂停 / 恢复 更新当前目标。恢复还会通过正常聊天准入启动继续。其内部输入保留在模型历史中，而不会显示为人类聊天消息。助手回复仍然可见。
• 垃圾桶 清除当前目标。
• 箭头 展开胶囊以显示完整目标内容、最新状态说明、Token 用量和经过时间。

在窄移动屏幕上，展开胶囊以在完整目标内容上方显示紧凑的带标签控件。折叠它会再次隐藏这些控件；Token 用量和经过时间仍位于目标内容和状态说明下方。

编辑、暂停和清除不会发送斜杠命令或添加聊天轮次。控件针对显示的目标 ID，因此过期按钮无法更改替换目标。如果请求被中断或其确认未在 30 秒内到达，UI 会报告未确认的结果。在恢复通知中使用 检查结果，即使目标已更改或已清除。这会原样重试已保存的操作，以将其与 Gateway 回执进行核对。原始请求会在此浏览器标签页中跨重连和重新加载保留；它永远不会自动重试。如果连接没有账户范围的恢复身份，或恢复请求无法保存，UI 不会发送目标控件；它会立即显示错误，说明为什么未发送该操作。隐身请求仅保留在内存中。成功重放会刷新当前状态，而不是恢复旧目标快照或启动另一个继续。关闭错误或取消编辑器不会取消已发送到 Gateway 的变更。24 小时后，已保存的请求过期，其字面载荷被移除；审查当前目标 会在下一次决策前刷新状态。忘记此浏览器或切换已认证账户会删除该 Gateway 之前的账户恢复载荷。

在未连接或初始聊天历史加载并确认会话身份期间，操作按钮不可用。展开箭头仍可正常工作。当有操作挂起时，并发的 Goal 操作会被拒绝。这些控件需要 Gateway 宣告结构化的 Goal 能力。文本 /goal 命令在 CLI 和其他支持命令的界面中仍然可用。

Gateway 请求与重试¶

Goal 启动使用 chat.send，以普通的 message 作为目标，并携带 intent: { kind: "session-goal-start", version: 1, issuedAtMs }。它保留常规的 idempotencyKey、附件和回复字段。按请求的运行时或投递路由覆盖会被拒绝。Goal 工作使用会话设置和本地投递，以便恢复时保持相同契约。目标必须包含非空白文本，且限制为 16,000 个字符。

sessions.goal.update 接受带有 objective 的 edit，或带有可选 note（最多 2,000 个字符）的 pause、resume、block 和 complete。 sessions.goal.clear 会移除 Goal。两种方法都要求 sessionKey、goalId、operationId 和 issuedAtMs。agentId 和 sessionId 可以固定目标。它们需要常规会话参与权限和 operator.write 作用域。

重试时请保留原始操作 ID、时间戳、目标和负载。回执自 issuedAtMs 起 24 小时内保持有效。比 Gateway 时钟超前超过五分钟的时间戳会被拒绝。使用不同请求重用某个 ID 会被拒绝。过期请求无法重新创建已清除的 Goal。每个会话的限制是 4,096 个未过期回执。达到该限制时，会拒绝新操作，直到回执过期，而不是驱逐有效的重试状态。

结果包含 operationId、action、sessionId、goalId 和 status（started、updated 或 cleared），如果存在还包括结果 goal，以及启动/恢复时的 runId。重放会添加 replayed: true：这是原始操作结果，而不是当前 Goal 状态。重放后请刷新会话。回执可防止重复的 Goal 变更和输入轮次。它们不保证外部工具或提供方的效果恰好一次。

TUI¶

TUI 页脚会在代理、会话和模型字段旁边，且在 token/模式指示器之前，保持当前会话的 Goal 可见。

页脚示例：

• Pursuing goal (12k/50k) 表示具有 token 预算的活动 Goal。
• Goal paused (/goal resume) 表示已暂停的 Goal。
• Goal blocked (/goal resume) 表示已阻塞的 Goal。
• Goal hit usage limits (/goal resume) 表示受使用限制影响的 Goal。
• Goal unmet (50k/50k) 表示受预算限制且未达成的 Goal。
• Goal achieved (42k) 表示已完成的 Goal。

页脚有意保持紧凑。使用 /goal 查看完整目标、备注、token 预算和可用命令。

通道行为¶

/goal 在支持命令的 OpenClaw 会话中可用，包括 TUI 和允许文本命令的聊天界面。Goal 状态绑定到会话键，而不是传输层，因此共享同一会话键的两个界面会看到相同的 Goal。

Goal 状态不是投递指令：它不会强制通过某个通道回复、更改队列行为、批准工具或安排工作。

故障排除¶

如果 token 使用量显示为 0 或看起来已过期，当前会话可能还没有新的 token 快照。随着 OpenClaw 记录会话使用量和由转录派生的总计，使用量会刷新。

相关¶

• 斜杠命令
• TUI
• 会话工具
• 压缩
• 常设命令