本页内容
本页内容
代理协调
目标
goal 是附加到当前 OpenClaw 会话的一个持久目标。它为代理和操作员提供了长期运行工作的共同目标。在内置聊天运行中,OpenClaw 在正常回合结束后继续追求主动目标,即使模型以最终答复结束而不是调用另一个工具也是如此。目标不是提醒、计划任务或常规命令。
目标是会话状态:它会随会话键移动,跨进程重启保留, 并会出现在 /goal、面向模型的目标工具以及 TUI 页脚中。
分离的命令完成后会返回到其源用户可见线程,因此即使命令执行使用了单独的沙盒策略会话,下一轮仍会继续看到相同的目标。
快速开始
start 是可选的:/goal get CI green for PR 87469 还创建一个目标,OpenClaw 将 /goal 之后的任何非已知动作词的文本视为新目标。
start 和 edit 等显式操作会保留目标内部的换行符、缩进和重复空格。前导和尾随空白被修剪。
目标的用途
当一次会话有一个具体的结果,并且需要在多个回合中保持可见时,请使用目标:
- 一个 PR 收尾:修复、验证、自动审查、推送,并打开或更新 PR。
- 一次调试运行:复现 bug,确定所属的范围,打补丁,并证明修复有效。
- 一次文档处理:阅读相关文档,编写新页面,建立交叉链接,并验证文档构建。
- 一项维护任务:检查当前状态,进行有界更改,运行正确的检查,并报告发生了什么变化。
目标不是任务队列。当工作应分离运行、按计划重复、扇出到托管子工作或作为策略保留时,请使用 subagents、cron 作业 或 常规订单。
命令参考
/goal 不带参数时会打印当前目标摘要:
| 命令 | 作用 |
|---|---|
/goal or /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 不采用代币预算标志。只有面向模型的 create_goal 工具才能设置预算。
状态
active:会话正在追求目标。paused:操作员暂停了目标,或者其运行因错误或超时而结束。/goal resume使其再次激活。失败的运行保留目标并将错误记录为状态注释;发送普通消息不会自动恢复目标。通过重试恢复的错误不会暂停它。blocked:代理或运营商报告了真正的拦截者。当新信息或状态可用时,/goal resume使其再次激活。budget_limited:已达到配置的代币预算。/goal resume以新的预算窗口从同一目标重新开始追求。usage_limited:为将来的使用限制停止状态保留。/goal resume以同样的方式重新开始追击。complete:目标达到了。它保持完整,直到您在 Control UI 中明确使用/goal resume或 Resume 再次追求相同的目标。恢复会保留其身份、创建时间和对话历史记录。除非达到预算,否则代币记账将继续,在这种情况下,恢复将启动一个新的预算窗口。稍后完成记录新的完成时间;重复完成而不恢复会保留原始时间,包括添加状态注释的时间。在开始不同的目标之前使用/goal clear。
/new 和 /reset 会清除当前会话目标,因为它们会刻意启动全新的会话上下文。
Token 预算
目标可以设置一个可选的正向 token 预算,通过 create_goal 工具的 token_budget 参数进行设置。该预算从目标创建时会话的最新 token 计数开始计算。如果目标开始时,会话只有过时或未知的 token 快照,OpenClaw 会等待下一次最新快照,并将其作为基线,因此在目标创建之前花费的 token 不会计入该目标。
除非您明确请求预算,否则模型应省略 token_budget。需要每个工具参数的传输无需预算即可通过 null。
当使用量达到预算时,目标将移至 budget_limited。这不会删除目标或消除目标。它告诉操作员和代理,在恢复或清除目标之前,不再主动追求目标。恢复以当前新代币计数启动新的预算窗口。
Token 预算是会话-目标级别的保护栏,而不是计费上限。提供方配额、成本报告以及上下文窗口行为仍然使用标准的 OpenClaw 用量和模型控制。
模型工具
OpenClaw 向代理运行环境暴露了三个目标工具:
| 工具 | 用途 |
|---|---|
get_goal |
读取当前会话目标:状态、目标、token 使用量以及 token 预算。 |
create_goal |
仅当用户或系统指令明确要求时才创建目标。如果会话中已存在目标,则失败。 |
update_goal |
将目标标记为 complete 或 blocked。 |
模型无法静默暂停、恢复、清除或替换目标。这些通过 /goal 和重置命令进行 operator/session 控制,因此代理可以报告成就或真正的拦截者,而无需悄悄移动目标。
仅当针对完整目标验证目标且没有剩余所需工作时,update_goal 才应标记目标 complete。只有在至少连续三个进球回合重复出现相同的阻挡条件后,才应标记进球 blocked,而不是因为普通难度或缺少抛光。恢复被阻止的目标将开始新的连续三轮计数。较早被阻挡的转弯不计入其中。几乎耗尽的预算并不能成为将未完成的工作标记为完成的理由。更新目标状态不会发送聊天回复。代理仍必须提供用户请求的最终响应。
每次回合的目标上下文
每个具有主动目标的 user/chat 回合都包含以下用户角色上下文行:
OpenClaw 通过截断较长的目标来保持这一行的简洁。已暂停、已阻塞、受预算限制、受用量限制以及已完成的目标不会被注入,因此,操作员的停止指令会一直生效,直到该目标恢复为止。
自动延续
内置聊天或自动回复轮正常完成后,OpenClaw 检查当前目标及其令牌使用情况。如果相同的目标仍然处于活动状态,则会将隐藏的内部微调排队:Advance the active goal;保持其活动状态直到完全实现。 每个成功结算的延续都会进行相同的检查;这不是一次性重试或固定次数的额外回合。
正常的后续队列拥有这些轮次。他们等待上一轮的执行和传递解决,使用正常的会话准入和权限,并且不会显示为新的人工消息。排队的用户输入和现有的 child/tool 延续优先;推动并不与他们并肩而行。目标和会话在入场时会再次检查,因此陈旧的排队推动无法追求清除、替换、完成、阻止、暂停或限制的目标。
Stop 取消当前工作和待处理的后续工作;它并不标志着未完成的目标已经完成。暂停可以防止进一步的目标转变。如上所述,终端错误和超时会暂停目标。恢复暂停或有限的目标仍然是显式操作员操作,而不是延续所做的事情。
自动微调适用于内置 chat/auto-reply 执行,而不是本机 Codex、其他外部运行时、心跳轮换或独立计划工作。他们使用现有的队列和运行生命周期,而不是定期的后台扫描程序。单独保存的活动目标不会在关闭后启动新流程或创建计划;正常会话恢复或另一个承认的回合提供了下一个执行机会。
Control UI
使用 Enter、Tab 或单击从命令选择器中选择 Goal,然后键入目标并选择 Start goal。键入 /goal start 后跟一个空格,或提交 /goal start 而不指定目标,也会打开目标模式。即使在关闭选择器之后,发送裸露的 /goal 也会打开编辑器,而不是向对话添加命令。无法提交空目标。
作曲家会显示“目标”标签和客观提示,以便您可以看到“发送”将执行什么操作。目标是文字文本:诸如 clear 之类的单词和诸如 /stop 之类的文本不会成为目标模式中的命令。退出或取消会将目标保留为正常的聊天草稿。完整粘贴的命令(例如 /goal start Fix the tests)和显式管理命令(例如 /goal status)保留其文本命令行为。
启动目标会在确认发送之前将目标、其用户回合和运行准入一起保存。失败的录取会使选秀完好无损,并且不会创建目标。失败的旧聊天发送与新打开的目标草稿保持分开,而不是填充其空目标。启动和恢复需要内置 OpenClaw 运行时和具有可恢复历史记录的空闲本地会话。它们不可用于本机 Codex 和其他外部运行时,并且不会排队或引导到另一个运行。 UI 报告不受支持或繁忙的会话,而不是创建非活动目标。
网络 Control UI 将目标显示为聊天编辑器上方的紧凑药丸:状态图标、状态标签(例如 Pursuing goal)、截断的目标和实时已用计时器。
主动目标使用绿色目标图标。暂停的目标使用中性暂停图标、正常的卡片表面和冻结的已用计时器。阻止或限制的目标使用琥珀色警告图标和有色卡片;已完成的目标使用绿色支票。状态标签不依赖颜色来识别每个状态。将鼠标悬停或聚焦于已暂停或已阻止目标的状态标签可读取其状态说明,包括错误暂停的原因。扩展的详细信息还显示完整的注释。
该胶囊带有内联控制:
- Pencil 打开具有当前目标的“编辑目标”编辑器。保存仅改变目标。取消会恢复之前的聊天草稿。
- 暂停/恢复 更新当前目标,包括在需要更多工作时恢复已实现的目标。恢复也通过正常的聊天许可开始延续。其内部输入保留在模型历史记录中,而不显示为人类聊天消息。助理回复仍然可见。
- Trash 清除当前目标。
- 下拉箭头 会展开胶囊,显示完整目标、最新状态注释、token 使用量和经过时间。
简历在折叠的药丸中保持可见,包括在狭窄的移动屏幕上。展开药丸以显示整个目标上方的其他紧凑标记控件。代币使用情况和经过的时间仍然低于目标和状态说明。
编辑、暂停和清除不会发送斜杠命令或添加聊天回合。控件以显示的目标 ID 为目标,因此过时的按钮无法更改替换目标。如果请求被中断或其确认未在 30 秒内到达,UI 会报告未确认的结果。恢复将 恢复目标... 在等待时保留在药丸中,并在超时或不可用响应后使用相同的已保存请求重试一次。如果仍未确认,请在药丸中使用 重试恢复。其他操作或目标已更改或已清除的请求,请在恢复通知中使用 检查结果。这些控件会按原样重试已保存的操作,以将其与网关收据进行协调。在重新连接和重新加载时,原始请求仍保留在该浏览器选项卡中;恢复它永远不会自动发送它。如果连接没有帐户范围的恢复标识或无法保存恢复请求,则 UI 不会发送目标控制;它立即显示一个错误,解释为什么未发送操作。隐身请求仅保留在内存中。成功的重播会刷新当前状态,而不是恢复旧的目标快照或开始另一个延续。消除错误或取消编辑器不会取消已发送到网关的突变。 24 小时后,保存的请求将过期,其文字负载将被删除; 回顾当前目标在做出另一个决定之前刷新状态。忘记此浏览器或切换经过身份验证的帐户会删除该网关以前的帐户恢复有效负载。
如果没有连接或加载初始聊天历史记录并确认会话身份,操作按钮将不可用。扩展 V 形继续工作。当操作挂起时,并发目标操作将被拒绝。这些控制需要一个网关来通告结构化目标功能。文本 /goal 命令仍然可用于 CLI 和其他支持命令的表面。
网关请求和重试
目标启动使用chat.send,以普通message为目标,intent: { kind: "session-goal-start", version: 1, issuedAtMs }。它保留正常的 idempotencyKey、附件和回复字段。每个请求的运行时或传递路由覆盖都会被拒绝。目标工作使用会话设置和本地交付,因此恢复保持相同的合同。目标必须包含非空白文本,并且字符数不得超过 16,000 个。
sessions.goal.update 接受 edit 和 objective,或 pause、resume、block 和 complete 以及最多 2,000 个字符的可选 note。 sessions.goal.clear 删除目标。两种方法都需要 sessionKey、goalId、operationId 和 issuedAtMs。 agentId 和 sessionId 可以固定目标。它们需要正常会话参与和 operator.write 范围。
保留原始操作 ID、时间戳、目标和负载以进行重试。收据自 issuedAtMs 起 24 小时内有效。比网关时钟早五分钟以上的时间戳将被拒绝。将 ID 重新用于不同的请求将被拒绝。过期的请求无法重新创建已清除的目标。每个会话的未过期收据限额为 4,096 份。点击它会拒绝新的操作,直到收据过期,而不是驱逐有效的重试状态。
结果包括 operationId、action、sessionId、goalId 和 status(started、updated 或 cleared),以及生成的 goal(如果存在) runId 为 start/resume. 重播添加了 replayed: true:这是原始运算结果,而不是当前的目标状态。重播后刷新会话。收据可防止重复的目标突变和输入轮次。他们不承诺一次性的外部工具或提供者效果。
TUI
TUI 页脚使活动会话的目标在 token/mode 指示器之前的智能体、会话和模型字段旁边可见。
页脚示例:
Pursuing goal (12k/50k)表示带有 token 预算的活动目标。Goal paused (/goal resume)表示已暂停的目标。Goal blocked (/goal resume)表示已阻塞的目标。Goal hit usage limits (/goal resume)表示受使用量限制的目标。Goal unmet (50k/50k)表示受预算限制的目标。Goal achieved (42k)表示已完成的目标。
页脚刻意保持紧凑。请使用 /goal 查看完整目标、 说明、token 预算以及可用命令。
频道行为
/goal 在支持命令的 OpenClaw 会话中工作,包括 TUI 和允许文本命令的聊天界面。目标状态附加到会话密钥,而不是传输,因此共享会话密钥的两个表面看到相同的目标。
目标状态不是交付指令:它不会强制通过渠道进行回复或批准工具。自动延续使用普通的后续队列及其传递、取消和接纳规则;它不会创建 cron 计划或绕过现有的延续所有者。
故障排查
| 消息 | 含义 |
|---|---|
Goal error: goal already exists |
会话中已经存在一个目标。使用 /goal 查看它,如果已完成则使用 /goal complete,或者在开始不同目标之前使用 /goal clear。 |
Goal error: goal not found |
会话中还没有目标。使用 /goal start <objective> 开始一个目标。 |
Goal error: goal is already complete |
在编辑、暂停或阻止目标之前,必须明确恢复该目标。清除它以开始不同的目标。 |
如果令牌用量显示为 0 或看起来是旧的,则当前活动会话可能还没有新的令牌快照。随着 OpenClaw 记录会话使用情况和基于转录的总计,使用量会刷新。