OpenClaw Goal 实战指南会话级目标的 /goal 命令、模型目标工具与 Token 预算机制【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw本文以 OpenClaw 的 Goal会话目标功能为主体完整覆盖 docs/tools/goal.md 中定义的所有实操内容——/goal命令族、六种状态机、token_budget预算机制、模型侧三个目标工具、Control UI 的 Gateway 协议与重试契约、TUI 展示与排障方法——并结合 OpenClaw 源码目标存储、状态迁移、协议 Schema逐项验证其底层实现帮助你在长会话中为目标驱动的 Agent 工作建立可见、可控、可审计的目标管理方案。Goal 是什么会话级持久目标在 OpenClaw 中goal目标是附加在当前会话上的一条持久性目标。它为 agent 和操作者提供了一个长期工作的共同指向但刻意不把它变成后台任务、提醒、cron 作业或常设指令。从源码结构看Goal 是典型的会话状态它挂在会话条目SessionEntry.goal字段上随 session key 迁移能跨进程重启存活并出现在三个地方——/goal命令输出、面向模型的目标工具goal tools、TUI 底部状态栏。一个值得注意的设计细节脱离式detached命令执行完成后其结果会回到发起它的用户可见线程因此即使命令执行本身使用了独立的沙箱策略会话下一轮对话依然能看到同一个 goal。快速上手最简使用方式/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 clearstart其实是可选的/goal get CI green for PR 87469同样会创建目标。OpenClaw 会把/goal后面所有不是已知动作词的文本都当作新目标文本。两个行为细节显式动作start、edit会保留目标文本中的换行、缩进和连续空格目标文本的首尾空白会被裁剪trim这与 src/config/sessions/goals.ts 中createSessionGoal对options.objective.trim()的处理一致且空目标会直接抛出objective required错误。Goal 的适用场景什么时候该用什么时候不该用当会话存在一个需要在很多轮对话中保持可见的具体成果时适合使用 goalPR 收尾修复、验证、自动评审、推送、创建或更新 PR调试任务复现 bug、定位负责的模块、打补丁、证明修复有效文档补写读相关文档、写新页面、加交叉链接、验证 docs 构建通过维护任务检查现状、做有边界的修改、跑对检查、汇报变更。反过来goal 不是任务队列。如果工作应该脱离会话运行、按计划重复、扇出成受管理的子任务、或作为持久策略存在应当使用 Task Flow、tasks、cron jobs 或 standing orders相关文档位于 docs/automation/ 目录。命令参考/goal不带参数时打印当前目标摘要。实际输出格式由 src/config/sessions/goals.ts 的formatSessionGoalStatus生成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 objectivestart的别名/goal objective同样创建新目标任何非动作词文本/goal edit objective改写当前目标文本状态和 token 记账保持不变/goal pause [note]暂停一个 active 目标/goal resume [note]恢复 paused、blocked、usage_limited 或 budget_limited 目标/goal complete [note]标记目标达成/goal done [note]complete的别名/goal block [note]标记目标受阻/goal blocked [note]block的别名/goal clear从会话中移除目标关键约束与限制一个会话同一时刻只能有一个 goal。再启动第二个会失败并报Goal error: goal already exists直到当前目标被清除。这一点在 src/config/sessions/goals-transitions.ts 的buildCreatedSessionGoal中得到印证只要entry.goal已存在就抛出SessionGoalTransitionError(goal already exists)。/goal start不接受 token-budget 参数。只有模型侧的create_goal工具可以设置预算见下文。/new和/reset会清除当前会话的目标因为它们的语义就是开启全新的会话上下文。命令的解析与执行入口在 src/auto-reply/reply/commands-goal.ts其状态输出逻辑与上文formatSessionGoalStatus的逐行结构一一对应。六种状态状态机与恢复规则状态含义与恢复方式active会话正在 pursuit 该目标paused操作者暂停了目标/goal resume恢复为 activeblockedagent 或操作者报告了真实阻塞有新信息或状态变化后/goal resume可恢复budget_limited达到配置的 token 预算/goal resume以全新的预算窗口从同一目标继续usage_limited为未来 usage-limit 停止状态保留恢复方式同上complete目标达成终态必须/goal clear后才能开始新目标重复 complete 会保留首次完成时间即使再次附加状态备注源码中的状态集合与协议 Schema 完全一致。SessionGoalSchema在 packages/gateway-protocol/src/schema/sessions-goal.ts 中定义status字段是一个六值联合active / paused / blocked / usage_limited / budget_limited / complete整个 schema 还携带tokenStart、tokenStartFresh、tokensUsed、tokenBudget可选、continuationTurns以及各状态的时间戳pausedAt、blockedAt、completedAt、usageLimitedAt、budgetLimitedAt——这些字段解释了/goal输出中 Tokens used 与 Token budget 两行的数据来源。complete的终态约束在 src/config/sessions/goals-transitions.ts 中实现已 complete 的目标拒绝任何非 complete 的状态变更且completedAt取首次完成时间accounted.completedAt ?? now这解释了重复完成保留原始完成时间的文档承诺。Token 预算记账原理与 budget_limited 迁移Goal 可以带一个可选的正整数 token 预算只能通过create_goal工具的token_budget参数设置。预算的记账规则在 src/config/sessions/goals-transitions.ts 的accountSessionGoalUsage中实现要点有三基线选择预算从目标创建时刻会话的fresh新鲜token 计数起算tokenStart。如果建目标时会话只有过期或未知的 token 快照tokenStartFresh为 falseOpenClaw 会等待下一个 fresh 快照再采用为基线——目标存在之前消耗的 token 不会记到目标头上。用量计算tokensUsed max(已记录用量, freshTotal - tokenStart)即已记账用量与fresh 总量减去基线取较大者避免快照回退导致用量倒退。自动迁移只要目标是active、配置了预算且tokensUsed tokenBudget状态立即迁移到budget_limited并记录budgetLimitedAt。达到预算不会删除目标或擦除目标文本它只是告诉 agent 和操作者在恢复或清除之前目标不再被主动 pursuit。/goal resume会从当前 fresh token 计数开启新的预算窗口——源码中src/config/sessions/goals-transitions.ts明确在 resume 时重置tokenStart为当前 fresh 总量、tokensUsed归零并清除budgetLimitedAt/usageLimitedAt标记。两个实践要点模型应当省略token_budget除非你明确要求设置预算对于要求所有工具参数必须显式给出的传输层可传null表示无预算工具 Schema 中token_budget的可选类型正是integer(minimum: 1) | null见 src/agents/tools/goal-tools.ts。Token 预算是会话目标的护栏不是计费上限。Provider 配额、成本报告、上下文窗口行为仍走 OpenClaw 常规 usage 与模型控制。模型目标工具get_goal / create_goal / update_goalOpenClaw 向 agent harness 暴露三个目标工具实现集中在 src/agents/tools/goal-tools.ts工具用途get_goal读取当前会话目标完整目标文本、状态、token 用量、可选预算create_goal仅当用户或系统指令明确要求时创建目标会话已有目标则失败update_goal将目标标记为complete或blocked权限边界模型不能静默地 pause、resume、clear 或替换目标——这些保留给操作者通过/goal与 reset 命令。因此 agent 可以报告达成或真实阻塞却无法悄悄移动目标本身。这个边界在源码中是硬编码的MODEL_UPDATABLE_SESSION_GOAL_STATUSES只含[complete, blocked]src/config/sessions/goals.tsupdate_goal的工具参数 Schema 直接由该常量生成枚举任何其它状态值都会抛出status must be one of complete, blocked的输入错误。update_goal的使用准则写进了工具 descriptionsrc/agents/tools/goal-tools.ts只有当完整目标被逐项验证、且无遗留必做工作时才标记complete只有当同一阻塞条件连续至少三个 goal turn 重复出现、且不靠用户输入或外部变化无法取得进展时才标记blocked普通难度或还差一点打磨不算blocked 目标被 resume 后连续计数从 3 重新起算此前的 blocked turn 不计入预算几乎耗尽不构成把未完成工作标记 complete 的理由更新目标状态不会向用户发送任何回复——agent 仍须提供用户要求的最终可见回复。两个实现细节值得注意update_goal成功后返回体里带nextAction提示明确要求模型继续本轮并给出可见最终回复src/agents/tools/goal-tools.ts当没有需要变更的活动目标时工具捕获SessionGoalTransitionError并返回status: error加不要重试 update_goal的指引而不是抛出异常——这让模型能优雅地结束本轮src/agents/tools/goal-tools.ts。测试覆盖可参考 src/agents/tools/goal-tools.test.ts。每轮注入的 Goal 上下文每个带 active goal 的用户/聊天轮次都会注入一行 user 角色上下文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.行为规则为保持紧凑长目标文本会被截断paused、blocked、budget_limited、usage_limited、complete状态的目标不注入——操作者的停止意图会一直生效直到目标被 resume。Control UIGoal Composer 与 Gateway 协议契约Web Control UI 中的 Goal 交互由 Gateway 的结构化能力支撑其请求/响应契约的权威定义在 packages/gateway-protocol/src/schema/sessions-goal.ts。Goal Composer在命令选择器中选Goal、输入目标文本并发送composer 会显示 Goal 标签让你看到 Send 将执行的动作。目标文本是字面量诸如clear这样的词、/stop这样的文本在 Goal 模式下不会变成命令。取消会把文本保留为普通聊天草稿。发送时序保证Start Goal 会把 Goal、其 user turn 和运行准入admission一起保存后才确认 Send准入失败则草稿原样保留、不创建 Goal。Start 与 Resume 要求本地会话空闲且历史可恢复不做排队或转向其他 runUI 对不支持或忙碌的会话直接报错而不是创建一个不活跃的 Goal。目标 Pill聊天 composer 上方显示紧凑 pill——状态图标、状态标签如Pursuing goal、截断目标、实时耗时计时器。内联控件铅笔打开 Edit Goal composer保存只改目标文本取消恢复之前的聊天草稿暂停/恢复更新当前 GoalResume 会经由正常聊天准入启动续跑其内部输入留在模型历史中、不呈现为人工聊天消息但助手回复可见垃圾桶清除当前 Goal展开箭头展开显示完整目标、最新状态备注、token 用量与耗时。Edit、Pause、Clear不发送斜杠命令、不添加聊天轮次控件指向展示时的 Goal ID因此陈旧按钮无法误改被替换的新 Goal。请求中断时原样重试成功重放会刷新当前状态而非恢复旧 Goal 快照。无连接时操作按钮不可用但展开箭头仍可用并发 Goal 操作在操作 pending 期间会被拒绝。这些控件要求 Gateway 声明了结构化 Goal 能力文本/goal命令在 CLI 等其它命令可用表面上始终可用。Gateway 请求与重试契约与协议 Schema 逐项对应启动Goal start 走chat.send普通message即目标文本另带intent: { kind: session-goal-start, version: 1, issuedAtMs }保留常规idempotencyKey、附件与回复字段拒绝按请求的运行时或投递路由覆盖——Goal 工作统一使用会话设置与本地投递使恢复保持同一契约。目标文本必须含非空白内容且上限 16,000 字符对应 Schema 中objective的maxLength: 16_000。更新/清除sessions.goal.update接受edit带objective或pause/resume/block/complete带可选note上限 2,000 字符sessions.goal.clear删除 Goal。两类方法都要求sessionKey、goalId、operationId、issuedAtMsagentId与sessionId可选用于精确锁定目标。两者要求正常的会话参与权限和operator.writescope服务端实现见 src/gateway/server-methods/sessions-goal.ts测试见 src/gateway/server-methods/sessions-goal.test.ts。重试与幂等收据重试时保持原 operation ID、时间戳、目标与载荷不变。收据自issuedAtMs起24 小时内有效早于 Gateway 时钟 5 分钟以上的时间戳被拒绝同一 ID 复用于不同请求被拒绝过期请求不能重建已清除的 Goal。每会话上限4,096 条未过期收据达到上限时拒绝新操作直至收据过期而不是驱逐有效重试状态。结果字段结果含operationId、action、sessionId、goalId、statusstarted/updated/cleared与 协议 Schema 的SessionsGoalMutationResultSchema一致以及存在时的最终goal和 start/resume 时的runId。重放会附加replayed: true——注意它是原始操作的结果而非当前 Goal 状态重放后应刷新会话。收据防止重复 Goal 变更与输入轮次但不承诺外部工具或 Provider 副作用的 exactly-once。TUI 底部状态栏TUI footer 在 agent、session、model 字段之后、token/mode 指示器之前保持当前会话目标的可见性Pursuing goal (12k/50k)——active 且带预算的目标Goal paused (/goal resume)——pausedGoal blocked (/goal resume)——blockedGoal hit usage limits (/goal resume)——usage_limitedGoal unmet (50k/50k)——budget_limitedGoal achieved (42k)——complete。footer 刻意保持紧凑完整目标文本、备注、token 预算与可用命令请用/goal查看展示逻辑见 src/shared/session-goal-display.ts。多通道行为与排障通道行为/goal在所有支持命令的 OpenClaw 会话中可用包括 TUI 与允许文本命令的聊天表面。Goal 状态挂在 session key 上而非传输层上因此共享同一 session key 的两个表面会看到同一个 goal。Goal 状态不是投递指令它不会强制回复走某个通道、不改变队列行为、不批准工具、也不调度工作。排障速查表消息含义Goal error: goal already exists会话已有目标。用/goal查看完成了就/goal complete想换目标先/goal clearGoal error: goal not found会话还没有目标。用/goal start objective创建Goal error: goal is already complete目标是终态。清除后才能开始或恢复新目标如果 token 用量显示0或看起来过期说明当前活跃会话还没有 fresh token 快照用量会在 OpenClaw 记录会话 usage 与从转录transcript推导的总量时刷新。对应源码逻辑即前文tokenStartFresh的基线采纳机制只有 fresh 快照到达后记账才会切换为实时总量差值。延伸阅读斜杠命令总览docs/tools/slash-commands.md自动化体系Task Flow、cron、standing ordersdocs/automation/Goal 状态迁移的单元测试src/config/sessions/goals.test.ts、src/config/sessions/goals-operations.test.tsGateway Goal 能力声明packages/gateway-protocol/src/server-capabilities.ts适用前提本文所述命令、协议字段与限额16,000 字符目标、2,000 字符备注、24 小时收据窗口、4,096 收据上限均以当前仓库中 docs/tools/goal.md 与 packages/gateway-protocol/src/schema/sessions-goal.ts 的定义为准Control UI 的结构化 Goal 控件依赖 Gateway 声明对应能力纯 CLI 环境请优先使用文本/goal命令。【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
