目标
目标(goal) 是附加到当前 OpenClaw 会话的一个持久目标。它为 agent 和操作者提供了一个长期工作的共同目标,而不会将该目标变成后台任务、提醒、cron 任务或常设指令。
目标是会话状态:它们随会话 key 一起迁移,在进程重启后仍然存在,并出现在 /goal、面向模型的 goal 工具以及 TUI 底部栏中。
独立运行的命令的完成结果会返回至发起它们的用户线程,因此即使命令执行使用了独立的沙箱策略会话,下一轮对话仍会看到相同的目标。
快速开始¶
/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 或 /goal status |
显示当前目标。 |
/goal start <objective> |
为当前会话创建一个新目标。 |
/goal set <objective>、/goal create <objective> |
start 的别名。 |
/goal <objective> |
也会创建一个新目标(任何不是已识别动作词的文本)。 |
/goal edit <objective> |
改写当前目标;状态和 token 计数保持不变。 |
/goal pause [note] |
暂停一个活动目标。 |
/goal resume [note] |
恢复已暂停、受阻、受用量限制或受预算限制的目标。 |
/goal complete [note] |
将目标标记为已达成。 |
/goal done [note] |
complete 的别名。 |
/goal block [note] |
将目标标记为受阻。 |
/goal blocked [note] |
block 的别名。 |
/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 为智能体框架公开了三个目标工具:
| Tool | Purpose |
|---|---|
get_goal |
读取当前会话目标:状态、目标描述、Token 用量和 Token 预算。 |
create_goal |
仅当用户或系统指令明确要求时才创建目标。如果会话已有目标,则失败。 |
update_goal |
将目标标记为 complete 或 blocked。 |
模型不能静默暂停、恢复、清除或替换目标。这些操作仍由操作员/会话通过 /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 通过截断长目标描述来保持该行紧凑。已暂停、受阻、预算受限、用量受限和已完成的目标不会被注入,因此操作员的停止操作会一直生效,直到目标被恢复。
控制界面¶
使用 Enter、Tab 或点击从命令选择器中选择 Goal,然后输入目标描述并选择 Start goal。输入 /goal start 后跟一个空格,或提交不带目标描述的 /goal start,也会打开 Goal 模式。单独发送 /goal,即使在关闭选择器之后,也会打开编辑器,而不是向对话添加命令。空目标描述无法提交。
编辑器会显示 Goal 标签和目标描述提示,以便你了解 Send 将执行的操作。目标描述是字面文本:诸如 clear 之类的词语和诸如 /stop 之类的文本在 Goal 模式下不会成为命令。按 Escape 或 Cancel 会将目标描述保留为普通聊天草稿。完整粘贴的命令(如 /goal start Fix the tests)和明确的管理命令(如 /goal status)保留其文本命令行为。
启动 Goal 会在确认 Send 之前一并保存该 Goal、其用户回合和运行准入(run admission)。准入失败时,草稿保持原样,且不会创建 Goal。较早的失败聊天发送会保持独立于新打开的 Goal 草稿,而不会填充其空目标描述。Start 和 Resume 需要内置的 OpenClaw 运行时,以及具有可恢复历史的空闲本地会话。它们不适用于原生 Codex 和其他外部运行时,也不会排队或被引导到另一个运行中。UI 会报告不受支持或忙碌的会话,而不是创建不活动的 Goal。
Web 控制界面在聊天编辑器上方以紧凑的药丸(pill)形式显示目标:状态图标、状态标签(例如 Pursuing goal)、截断的目标描述和实时已用时间计时器。
活动目标使用绿色目标图标。已暂停目标使用中性暂停图标、普通卡片表面和冻结的已用时间计时器。受阻或受限目标使用琥珀色警告图标和着色卡片;已完成目标使用绿色对勾。状态标签标识每种状态,而不依赖颜色。将鼠标悬停或聚焦于已暂停或受阻目标的状态标签,即可阅读其状态说明,包括错误暂停的原因。展开的详细信息还会显示完整说明。
该药丸带有内联控件:
- Pencil(铅笔):使用当前目标描述打开 Edit Goal 编辑器。保存仅更改目标描述。取消会恢复之前的聊天草稿。
- Pause / resume(暂停/恢复):更新当前 Goal。恢复还会通过正常聊天准入启动一次延续。其内部输入保留在模型历史中,不会作为人类聊天消息出现。助手回复仍然可见。
- Trash(垃圾桶):清除当前 Goal。
- Chevron(V 形图标):展开药丸,显示完整目标描述、最新状态说明、Token 用量和已用时间。
在窄屏移动设备上,展开药丸可在完整目标描述上方显示紧凑的带标签控件。折叠后会再次隐藏这些控件;Token 用量和已用时间仍保留在目标描述和状态说明下方。
Edit、Pause 和 Clear 不会发送斜杠命令,也不会添加聊天回合。控件作用于显示的 Goal ID,因此过期的按钮无法更改替换后的 Goal。如果请求被中断或其确认在 30 秒内未到达,UI 会报告未确认的结果。即使目标已更改或被清除,也请使用恢复通知中的 Check outcome。这会按原样重试已保存的操作,以与 Gateway 回执进行对账。原始请求在重连和重新加载期间保留在此浏览器标签页中;它绝不会被自动重试。如果连接没有账户级恢复身份,或恢复请求无法保存,UI 不会发送目标控件;它会立即显示错误,说明操作未发送的原因。无痕模式下的请求仅保留在内存中。成功的重放会刷新当前状态,而不是恢复旧的 Goal 快照或启动另一次延续。关闭错误或取消编辑器,并不会取消已发送到 Gateway 的变更。24 小时后,已保存的请求过期,其字面负载将被移除;Review current goal 会在做出另一个决定之前刷新状态。忘记此浏览器或切换已认证账户,会移除该 Gateway 之前的账户恢复负载。
在没有连接的情况下,或在初始聊天历史加载并确认会话身份期间,操作按钮不可用。展开箭头仍可正常工作。当有操作挂起时,并发的 Goal 操作会被拒绝。这些控件需要 Gateway 声明结构化 Goal 能力。文本 /goal 命令在 CLI 和其他支持命令的界面中仍然可用。
网关请求与重试¶
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 页脚会在 agent、session 和 model 字段旁边显示当前会话的 goal,位于 token/模式指示器之前。
页脚示例:
- 对于具有 token 预算的活跃 goal,显示
Pursuing goal (12k/50k)。 - 对于已暂停的 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 查看完整目标、备注、token 预算和可用命令。
通道行为¶
/goal 在支持命令的 OpenClaw 会话中可用,包括允许文本命令的 TUI 和聊天界面。Goal 状态绑定到会话键,而不是传输层,因此共享同一会话键的两个界面会看到同一个 goal。
Goal 状态不是投递指令:它不会强制通过某个通道回复、更改队列行为、批准工具或安排工作。
故障排除¶
| 消息 | 含义 |
|---|---|
Goal error: goal already exists |
会话已经有一个 goal。使用 /goal 检查它,如果已完成则使用 /goal complete,或在开始不同目标前使用 /goal clear。 |
Goal error: goal not found |
会话还没有 goal。使用 /goal start <objective> 启动一个。 |
Goal error: goal is already complete |
该 goal 已处于终态。在启动或恢复另一个目标之前清除它。 |
如果 token 用量显示为 0 或看起来已过期,当前会话可能还没有新的 token 快照。当 OpenClaw 记录会话用量和由转录派生的总计时,用量会刷新。
相关¶
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw