Goal

A goal is one durable objective attached to the current OpenClaw session. It gives the agent and the operator a shared target for long-running work. In built-in chat runs and supported local or cloud-worker Codex sessions, OpenClaw continues pursuing an active goal after a normal turn finishes, even when the model ends with a final reply instead of calling another tool. A goal is not a reminder, cron job, or standing order.

Local Codex sessions also support explicit Resume of an existing goal. Resume retains the goal identity, objective, and conversation history. If current work is still active, wait for it to settle before retrying Resume.

Goals are session state: they move with the session key, survive process restarts, and appear in /goal, the model-facing goal tools, and the TUI footer.

Detached command completions return to the originating user-facing thread, so the next turn continues to see the same goal even when command execution used a separate sandbox policy session.

Quick start

/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 is optional: /goal get CI green for PR 87469 also creates a goal, OpenClaw treats any text after /goal that is not a known action word as a new objective.

Explicit actions such as start and edit preserve line breaks, indentation, and repeated spaces inside the objective. Leading and trailing whitespace is trimmed.

What goals are for

Use a goal when a session has a concrete outcome that should stay visible across many turns:

• A PR closeout: fix, verify, autoreview, push, and open or update the PR.
• A debug run: reproduce the bug, identify the owning surface, patch, and prove the fix.
• A docs pass: read the relevant docs, write the new page, cross-link it, and verify the docs build.
• A maintenance task: inspect current state, make bounded changes, run the right checks, and report what changed.

A goal is not a task queue. Use subagents, cron jobs, or standing orders when work should run detached, repeat on a schedule, fan out into managed sub-work, or persist as a policy.

Command reference

/goal with no arguments prints the current goal summary:

GoalStatus: activeObjective: get CI green for PR 87469 and push the fixTokens used: 12kToken budget: 12k/50k Commands: /goal edit <objective>, /goal pause, /goal complete, /goal clear

Only one goal can exist on a session at a time. In the Control UI, submitting a new objective through /goal <objective> or the Goal composer asks whether to replace the current objective. For an idle or paused goal, confirming uses Edit and preserves its status. For an executing active goal, confirming interrupts that exact turn, waits for its work to settle, pauses and edits the same goal, then resumes it through normal continuation admission. Its identity, token accounting, budget, and history are retained; replacement does not reset an exhausted budget. Canceling leaves running work untouched and keeps the proposed objective in the composer. Completed goals cannot be edited.

The decision is bound to the displayed session, goal revision, and executing turn. If those change before interruption, review the current goal and confirm again; a stale decision never interrupts a newer turn. If a later stage fails, replacement stops there without automatically resuming. The saved request can reconcile or retry completed stages using their existing durable receipts. Changing the goal with another control invalidates that recovery decision. If interruption cannot be verified, review the stopped or running goal and use its explicit controls; replacement never guesses that it is safe to resume. A warning that interrupted output could not be saved also stops replacement before the objective is edited or resumed; copy any visible text as the warning instructs.

In textual CLI/TUI commands, starting a second goal still fails with Goal error: goal already exists until the current one is cleared.

/goal start does not take a token-budget flag. Only the model-facing create_goal tool can set a budget.

Statuses

• active: the session is pursuing the goal.
• paused: the operator paused or stopped the goal, or its run ended with an error or timeout. /goal resume makes it active again. A failed run preserves the objective and records the error as a status note; sending an ordinary message does not automatically resume the goal. Errors that recover through a retry do not pause it.
• blocked: the agent or operator reported a real blocker. /goal resume makes it active again when new information or state is available.
• budget_limited: the configured token budget was reached. /goal resume restarts pursuit from the same objective with a fresh budget window.
• usage_limited: reserved for a future usage-limit stop state. /goal resume restarts pursuit the same way.
• complete: the goal was achieved. It stays complete until you explicitly use /goal resume or Resume in the Control UI to pursue the same objective again. Resuming preserves its identity, creation time, and conversation history. Token accounting continues unless the budget was reached, in which case resume starts a fresh budget window. A later completion records a new completion time; repeating completion without resuming preserves the original time, including when you add a status note. Use /goal clear before starting a different goal.

/new and /reset clear the current session goal, since they intentionally start fresh session context.

Token budgets

Goals can have an optional positive token budget, set through the create_goal tool's token_budget parameter. The budget is measured from the session's fresh token count at goal-creation time. If the session only has a stale or unknown token snapshot when the goal starts, OpenClaw waits for the next fresh snapshot and uses that as the baseline, so tokens spent before the goal existed are not charged to it.

The model should omit token_budget unless you explicitly request a budget. Transports that require every tool argument can pass null for no budget.

When usage reaches the budget, the goal moves to budget_limited. This does not delete the goal or erase the objective. It tells the operator and the agent that the goal is no longer actively being pursued until it is resumed or cleared. Resuming starts a new budget window at the current fresh token count.

Token budgets are a session-goal guardrail, not a billing cap. Provider quota, cost reporting, and context-window behavior still use the normal OpenClaw usage and model controls.

Model tools

OpenClaw exposes three goal tools to agent harnesses:

The model cannot silently pause, resume, clear, or replace a goal. Those stay operator/session controls through /goal and reset commands, so the agent can report achievement or a genuine blocker without quietly moving the target.

update_goal should mark a goal complete only when the objective is verified against the full objective with no required work remaining. It should mark a goal blocked only after the same blocking condition recurs for at least three consecutive goal turns, not for ordinary difficulty or missing polish. Resuming a blocked goal starts a fresh count of three consecutive turns. Earlier blocked turns do not count toward it. A nearly exhausted budget does not justify marking unfinished work complete. Updating goal status does not send a chat reply. The agent must still provide the user's requested final response.

Goal context on every turn

Every user/chat turn with an active goal includes this user-role context line:

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 keeps the line compact by truncating long objectives. Paused, blocked, budget-limited, usage-limited, and complete goals are not injected, so an operator stop remains in effect until the goal is resumed.

Automatic continuation

After a built-in chat or auto-reply turn finishes normally, OpenClaw checks the current goal and its token usage. If the same goal is still active, it queues a hidden internal nudge: Advance the active goal; keep it active until fully achieved. Each successfully settled continuation makes the same check; this is not a one-shot retry or a fixed number of extra turns.

The normal follow-up queue owns these turns. They wait for the previous turn's execution and delivery to settle, use normal session admission and permissions, and do not appear as new human messages. Queued user input and existing child/tool continuations take precedence; the nudge does not run alongside them. Children collected within the turn do not block continuation merely because they were spawned. When a built-in chat Goal yields to children, their settled requester turn receives the current Goal context. A normal final returns pursuit to the same follow-up queue only after the child completion batch is committed; it does not make independent command runs autonomous. The goal and session are checked again at admission, so a stale queued nudge cannot pursue a cleared, replaced, completed, blocked, paused, or limited goal.

Stop cancels the current work and pending follow-ups, and pauses an active unfinished goal with a status note explaining the stop; it does not mark the goal complete. Once the stopped work has fully settled, Resume can pursue the same goal again without clearing its history. Pause prevents further goal turns. Terminal errors and timeouts pause the goal as described above. Resuming a paused or limited goal remains an explicit operator action, not something the continuation does.

Each settled automatic Goal turn increments continuationTurns once, including the turn that completes the Goal. Human Start and Resume turns do not increment it.

Automatic nudges apply to built-in chat/auto-reply execution and supported local and cloud-worker Codex sessions, not other external runtimes, heartbeat turns, or independent scheduled work. They use the existing queue and run lifecycle rather than a periodic background scanner. A saved active goal alone does not start a new process or create a schedule after shutdown; normal session recovery or another admitted turn provides the next execution opportunity.

Control UI

Select Goal from the command picker with Enter, Tab, or a click, then type the objective and choose Start goal. Typing /goal start followed by a space (also set or create), or submitting an empty creation command, also opens Goal mode. Sending bare /goal opens the composer instead of adding a command to the conversation. An empty objective cannot be submitted.

Shorthand typing opens Goal mode immediately once the objective cannot be a supported subcommand: /goal l is enough. The command prefix is consumed, so /goal land it shows only land it in the Goal box. Explicit creation starters consume the action word too: /goal start followed by a space opens an initially empty Goal box that stays open while you begin typing.

Deleting the entire command-origin objective returns to command mode with /goal and a following space repopulated, with the caret at the end. Backspace or Delete in an already-empty command-origin Goal box does the same. Valid command prefixes such as /goal sta keep completion; typing an unambiguous objective enters Goal mode again. Complete pasted creation commands follow the same path. Enter submits the literal objective immediately, without a timer, and empty objectives are never submitted. Explicit management commands such as /goal status remain commands.

The composer shows a Goal label and an objective prompt so you can see what Send will do. Once in Goal mode, the objective is literal text: words such as clear and text such as /stop do not become commands. Picker-opened creation and existing-Goal editing stay in their own modes when emptied. Escape or Cancel leaves the current objective as a normal chat draft; canceling an existing-Goal edit restores its borrowed conversation draft.

Starting a Goal saves the Goal and its user turn together with the operation receipt before acknowledging Send. A failed admission leaves the draft intact and does not create a Goal. A failed older chat send stays separate from a newly opened Goal draft instead of filling its empty objective. Start and Resume require an idle built-in local session with recoverable history, or an idle existing Codex session running locally or on a cloud worker with remote execution. Codex input must pass native admission before the runtime commits the Goal and its operation receipt. Cloud-worker sessions also require worker setup to admit that input. Other external runtimes remain unsupported. Goals are not queued or steered into another run. The UI reports unsupported or busy sessions rather than creating an inactive Goal.

Codex worker Goals use the same OpenClaw Goal ID, history, budgets, accounting, and continuation queue. Codex's separate autonomous Goal engine stays disabled; the core get_goal, create_goal, and update_goal tools remain available when native shell tools are enabled, subject to normal tool policy. Continuation retains the operator's current authority; it does not replay old input or recreate authority after a Gateway restart.

The web Control UI shows the goal as a compact pill above the chat composer: a status icon, the status label (for example Pursuing goal), the truncated objective, and a live elapsed timer. Seconds appear only below one minute; longer durations use whole minutes (4m) or hours and minutes (2h 5m). Day and week durations retain the remaining hours and minutes, including zeros (for example 1d 0h 0m or 1wk 5d 17h 15m), so long-running goals stay precise without a seconds counter.

Active goals use a green target icon. Paused goals use a neutral pause icon, the normal card surface, and a frozen elapsed timer. Blocked or limited goals use an amber warning icon and tinted card; completed goals use a green check. Status labels identify each state without relying on color. Hover or focus a paused or blocked goal's status label to read its status note, including the reason for an error pause. The expanded details also show the full note.

The pill carries inline controls:

• Pencil opens an Edit Goal composer with the current objective. Saving changes only the objective. Cancelling restores the previous chat draft.
• Pause / resume updates the current Goal, including resuming an achieved Goal when more work is warranted. Resume also starts a continuation through normal chat admission. Its internal input stays in model history without appearing as a human chat message. The assistant reply remains visible.
• Trash clears the current Goal.
• Chevron expands the pill to show the full objective, the latest status note, token usage, and elapsed time.

Resume stays visible in the collapsed pill, including on narrow mobile screens. It is disabled while the session is sending, queued, or running another turn; Pause, Edit, and Clear remain available. A saved Resume request can still be checked to reconcile its outcome without starting another turn. Expand the pill to reveal the other compact labeled controls above the full objective. Token usage and elapsed time remain below the objective and status note.

Edit, Pause, and Clear do not send slash commands or add chat turns. Controls target the displayed Goal ID, so a stale button cannot change a replacement Goal. If a request is interrupted or its acknowledgment does not arrive within 30 seconds, the UI reports an unconfirmed outcome. Resume keeps Resuming goal… in the pill while waiting and retries once after a timeout or unavailable response, using the same saved request. If it remains unconfirmed, use Retry resume in the pill. Other actions, or requests whose goal changed or was cleared, use Check outcome in the recovery notice. These controls retry the saved action unchanged to reconcile it with the Gateway receipt. The original request stays in this browser tab across reconnects and reloads; restoring it never sends it automatically. The UI does not send goal controls if the connection has no account-scoped recovery identity or the recovery request cannot be saved; it immediately shows an error explaining why the action was not sent. Incognito requests stay in memory only. A successful replay refreshes the current state instead of restoring an old Goal snapshot or starting another continuation. Dismissing an error or cancelling an editor does not cancel a mutation already sent to the Gateway. After 24 hours, the saved request expires and its literal payload is removed; Review current goal refreshes state before another decision. Forgetting this browser or switching authenticated accounts removes that Gateway's previous account recovery payloads.

The action buttons are unavailable without a connection or while the initial chat history loads and confirms the session identity. The expand chevron keeps working. Concurrent Goal actions are rejected while an operation is pending. These controls require a Gateway advertising the structured Goal capability. Text /goal commands remain available for CLI and other command-capable surfaces.

Gateway requests and retries

Goal start uses chat.send with the ordinary message as the objective and intent: { kind: "session-goal-start", version: 1, issuedAtMs }. It keeps the normal idempotencyKey, attachment, and reply fields. Per-request runtime or delivery-route overrides are rejected. Goal work uses the session settings and local delivery so recovery keeps the same contract. Objectives must contain non-whitespace text and are limited to 16,000 characters.

sessions.goal.update accepts replace with objective, the session ID, expectedGoalUpdatedAt, and expectedRunId for a confirmed executing-goal replacement; edit with objective; or pause, resume, block, and complete with an optional note of at most 2,000 characters. sessions.goal.clear removes the Goal. Both methods require sessionKey, goalId, operationId, and issuedAtMs. agentId and sessionId can pin the target. They require normal session participation and operator.write scope.

Keep the original operation ID, timestamp, target, and payload for retries. Receipts remain valid for 24 hours from issuedAtMs. Timestamps more than five minutes ahead of the Gateway clock are rejected. Reusing an ID with a different request is rejected. Expired requests cannot recreate a cleared Goal. The per-session limit is 4,096 unexpired receipts. Hitting it rejects new operations until receipts expire rather than evicting valid retry state.

Results include operationId, action, sessionId, goalId, and status (started, updated, or cleared), plus the resulting goal when present and runId for start/resume. A replay adds replayed: true: this is the original operation result, not the current Goal state. Refresh the session after replay. Receipts prevent duplicate Goal mutations and input turns. They do not promise exactly-once external tool or provider effects.

TUI

The TUI footer keeps the active session's goal visible next to the agent, session, and model fields, before token/mode indicators.

Footer examples:

• Pursuing goal (12k/50k) for an active goal with a token budget.
• Goal paused (/goal resume) for a paused goal.
• Goal blocked (/goal resume) for a blocked goal.
• Goal hit usage limits (/goal resume) for a usage-limited goal.
• Goal unmet (50k/50k) for a budget-limited goal.
• Goal achieved (42k) for a completed goal.

The footer is intentionally compact. Use /goal for the full objective, note, token budget, and available commands.

Channel behavior

/goal works in command-capable OpenClaw sessions, including the TUI and chat surfaces that permit text commands. Goal state attaches to the session key, not the transport, so two surfaces sharing a session key see the same goal.

Goal state is not a delivery directive: it does not force replies through a channel or approve tools. Automatic continuation uses the ordinary follow-up queue and its delivery, cancellation, and admission rules; it does not create a cron schedule or bypass an existing continuation owner.

Troubleshooting

If token usage shows 0 or looks stale, the active session may not have a fresh token snapshot yet. Usage refreshes as OpenClaw records session usage and transcript-derived totals.

Related

• Slash commands
• TUI
• Session tool
• Compaction
• Standing orders