Session Goals in OpenClaw: Set, Manage, and Track

Goal

A goal is a single, lasting objective tied to the active OpenClaw session. It gives both the agent and the operator a common aim for extended work, without converting that aim into a background process, reminder, scheduled job, or persistent directive.

Goals are part of session state: they travel with the session key, persist across process restarts, and show up in /goal, the model-facing goal tools, and the TUI footer.

When a command runs detached, its completion returns to the original user-facing thread. That means the next turn still sees the same goal, even if the command executed under 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 not required: /goal get CI green for PR 87469 will also establish a goal, because any text following /goal that is not a recognized action word is interpreted as a new objective.

What goals are for

Reach for a goal when a session has a specific outcome that needs to remain visible over many turns:

• Closing out a PR: fix, verify, autoreview, push, then open or update the PR.
• Debugging: reproduce the bug, locate the owning surface, apply a patch, and demonstrate the fix.
• A documentation pass: read the relevant docs, draft the new page, link to it, and confirm the docs build.
• Maintenance: inspect the current state, make limited changes, execute the proper checks, and summarize what changed.

A goal is not a task queue. When work should run detached, recur on a schedule, split into managed sub-work, or remain as a policy, use Task Flow, tasks, cron jobs, or standing orders instead.

Command reference

Running /goal without arguments shows the current goal summary:

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

A session can hold only one goal at a time. Attempting to start a second one fails with Goal error: goal already exists until the existing goal is removed.

/goal start accepts no token-budget flag; the only way to set a budget is through the model-facing create_goal tool.

Statuses

• active: the session is actively working toward the goal.
• paused: the operator put the goal on hold; /goal resume returns it to active status.
• blocked: either the agent or the operator logged a genuine blocker; /goal resume resumes active pursuit once fresh information or state is available.
• budget_limited: the assigned token budget was exhausted; /goal resume resumes pursuit from the same objective with a new budget window.
• usage_limited: set aside for a future usage-limit stop condition; /goal resume resumes pursuit in the same manner.
• complete: the goal was completed. Completed goals are terminal; run /goal clear before establishing another goal.

Because /new and /reset intentionally begin with a clean session context, they also remove the current session goal.

Token budgets

Goals may carry an optional positive token budget, configured via the create_goal tool's token_budget parameter. That budget is measured from the session's fresh token count at the moment the goal is created. 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 consumed before the goal existed are not counted against it.

Once usage hits the budget, the goal shifts to budget_limited. This neither deletes the goal nor discards the objective; it signals to the operator and the agent that the goal is no longer being pursued until it is resumed or cleared. Resuming opens a new budget window starting at the current fresh token count.

Token budgets act as a guardrail for the session goal, not as a billing cap. Provider quota, cost reporting, and context-window behavior continue to follow the standard OpenClaw usage and model controls.

Model tools

OpenClaw makes three goal tools available to agent harnesses:

The model cannot silently pause, resume, clear, or swap a goal. Those actions remain operator/session controls through /goal and reset commands, so the agent can report achievement or a real blocker without quietly shifting the target.

update_goal should only be applied to a goal complete once the objective has genuinely been met. A goal should receive blocked solely after the same blocking condition shows up for at least three consecutive goal turns, not for routine difficulty or incomplete refinement. Changing a goal's status never triggers a chat reply; the agent still has to supply the final response the user asked for.

Goal context on every turn

Every user or chat turn tied to an active goal carries 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 brief by shortening lengthy objectives. Goals that are paused, blocked, budget-limited, usage-limited, or complete are left out of the injection, so an operator stop stays in force until the goal gets resumed.

Control UI

In the web Control UI, the goal appears as a small pill above the chat composer, showing a status icon, the status label (such as Pursuing goal), the shortened objective, and a live elapsed timer.

The pill comes with inline controls:

• Pencil fills the composer with /goal edit <objective> so the objective can be reworded and sent again.
• Pause / resume switches between /goal pause and /goal resume depending on the current state.
• Trash dispatches /goal clear.
• Chevron opens the pill to reveal the full objective, the most recent status note, token usage, and elapsed time.

While the composer is unable to send (for instance, when the gateway connection is down), the action buttons stay hidden; the expand chevron continues to function.

TUI

The TUI footer keeps the active session's goal visible beside the agent, session, and model fields, positioned before token and 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 stays intentionally minimal. Turn to /goal for the complete objective, note, token budget, and available commands.

Channel behavior

/goal operates in OpenClaw sessions that support commands, covering the TUI and chat surfaces where text commands are allowed. Goal state attaches to the session key rather than the transport, so two surfaces sharing a session key observe the same goal.

Goal state is not a delivery directive: it never forces replies through a channel, alters queue behavior, approves tools, or schedules work.

Troubleshooting

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

Related

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