0cb59d88ff
* docs: fix checkable ux defects in docs/cli and docs/concepts
Works the subset of open `ux` audit findings for docs/cli/ and
docs/concepts/ where the finding names something objectively checkable
against the current tree or the source: a missing prerequisite, a
self-contradiction, an unstated default, or a step a reader cannot
execute as written. Stylistic rows ("add an intro paragraph", "this
section is dense", "consider a table") are left open.
Missing prerequisites and unexecutable steps:
- cli/voicecall: page says the plugin must be installed and enabled but
never gives the commands (r3-1260).
- cli/acp: the `acpx` section uses the external `acpx` npm CLI without
saying where it comes from, and the page also uses `acpx` for the
unrelated `@openclaw/acpx` Gateway plugin, which installs no binary
(r3-1236).
- concepts/memory-builtin: "Run interactive llama.cpp setup once" names
no command; it is `openclaw onboard` (r3-1445).
- concepts/memory-honcho: setup prompts for API credentials the page
never says how to obtain (r3-1476).
- concepts/personal-agent-benchmark-pack: the run command needs a source
checkout and OPENCLAW_ENABLE_PRIVATE_QA_CLI=1, neither stated
(r3-1481).
Contradictions:
- concepts/delegate-architecture: the bindings example configures the
same `delegate` agent with a weaker deny list than the tool-policy
section two screens up, dropping write/edit/apply_patch from an agent
the page says is locked down (r3-1453).
- cli/config vs cli/models: `config set` rejects a model reference it
cannot resolve, `models set` saves it with a warning. Both were
correct and neither said the other existed (r3-1178).
- concepts/typing-indicators: the Defaults list omits the
message-tool-only rule, which resolveTypingMode() applies ahead of the
group rules the list does give (r3-1494).
Missing elements and stale terms:
- concepts/main-session: names the default `all` visibility without
`tools.sessions.visibility` (r5-0010).
- cli/path: never links /plugins/oc-path (r3-1211).
- cli/agents: two Related lists that had drifted apart (r3-1282).
- cli/tasks: the only docs/cli title carrying literal backticks
(r3-1304).
- cli/worker: internal roadmap term "milestone-3 placement owner"
(r3-1268).
- concepts/delegate-architecture: Azure AD is now Microsoft Entra ID
(r3-1452).
- concepts/multi-agent: a JSON5 config example fenced as `js` while the
page's other two use `json5` (r3-1378).
No heading text changed, so no anchor id is added or dropped; verified
with parseDocsDocument over all 15 pages before and after. Adds the two
zh-CN glossary sources check-docs-i18n-glossary requires, each beside a
related existing entry rather than appended at the end.
* docs(models): scope the config-set validation comparison to text models
ClawSweeper P2 on docs/cli/models.md:38. The paragraph covers both
`models set` and `models set-image`, so "the same setting" implied that
`config set agents.defaults.imageModel.primary` also rejects an
unresolvable model. It does not: `pathMayAffectTextModelRefs` in
src/cli/config-model-validation.ts:52 returns true for
`agents.defaults` only when `path[2] === "model"`, so `imageModel` is
excluded and the config mutation validator never runs a model check on
it.
Names `agents.defaults.model` explicitly and says the check is
text-model only, rather than leaving readers to infer a validation
guarantee `config set` does not provide for image models.
5.8 KiB
| summary | read_when | title | doc-schema-version | ||
|---|---|---|---|---|---|
| CLI reference for `openclaw tasks` (background task ledger and Task Flow state) |
|
Tasks | 1 |
Inspect durable background tasks and Task Flow state. With no subcommand,
openclaw tasks is equivalent to openclaw tasks list.
See Background Tasks for the lifecycle and delivery
model, and its tasks audit section for full finding descriptions.
Usage
openclaw tasks
openclaw tasks list
openclaw tasks list --runtime acp
openclaw tasks list --status running
openclaw tasks list --status blocked
openclaw tasks show <lookup>
openclaw tasks notify <lookup> state_changes
openclaw tasks cancel <lookup>
openclaw tasks retry <lookup> [lookup...]
openclaw tasks dismiss <lookup> [lookup...]
openclaw tasks audit
openclaw tasks maintenance
openclaw tasks maintenance --apply
openclaw tasks flow list
openclaw tasks flow show <lookup>
openclaw tasks flow cancel <lookup>
Root Options
| Flag | Description |
|---|---|
--json |
Output JSON. |
--runtime <name> |
Filter by kind: subagent, acp, cron, or cli. |
--status <name> |
Filter by status: queued, running, succeeded, failed, timed_out, cancelled, lost, or blocked. |
Subcommands
list
openclaw tasks list [--runtime <name>] [--status <name>] [--json]
Lists tracked background tasks newest first.
Use --status blocked to find completed tasks whose result delivery is blocked.
These tasks retain their stored succeeded status and also remain included in
--status succeeded results; JSON task records keep the same stored status and
terminalOutcome fields.
show
openclaw tasks show <lookup> [--json]
Shows one task by task ID, run ID, or session key.
notify
openclaw tasks notify <lookup> <done_only|state_changes|silent>
Changes the notification policy for a running task.
cancel
openclaw tasks cancel <lookup>
Cancels a running background task.
retry
openclaw tasks retry <lookup> [lookup...]
Retries 1-10 blocked subagent completion deliveries. The child execution stays successful; retry creates a fenced delivery generation from the retained canonical result. An ambiguous earlier acknowledgement can still cause a duplicate visible result.
Retry and dismissal select the task's exact retained run, never another result from the same child session. Unrelated parent turns leave suspended completions blocked until you retry them. Upgrading from an older release repairs missing task bindings before loading runs, including runs that have not finished yet. Only unambiguous bindings are repaired; conflicting records remain unchanged and cannot be recovered by guessing from a shared session.
dismiss
openclaw tasks dismiss <lookup> [lookup...]
Records intentional non-delivery for 1-10 blocked subagent completions. The task continues to show a blocked terminal outcome and retains its result until the 7-day completion-retention window expires.
audit
openclaw tasks audit [--severity <warn|error>] [--code <name>] [--limit <n>] [--json]
Surfaces stale, lost, delivery-failed, or otherwise inconsistent task and
Task Flow records. Lost tasks retained until cleanupAfter are warnings;
expired or unstamped lost tasks are errors.
--code accepts task codes (stale_queued, stale_running, lost,
delivery_failed, missing_cleanup, inconsistent_timestamps) and additional
Task Flow codes (restore_failed, stale_waiting, stale_blocked,
cancel_stuck, missing_linked_tasks, blocked_task_missing). See
Background Tasks for severity and trigger detail per
code.
maintenance
openclaw tasks maintenance [--apply] [--json]
Previews or applies task and Task Flow reconciliation, cleanup stamping, pruning, and stale cron run session registry cleanup.
For cron tasks, reconciliation uses persisted run logs/job state before
marking an old active task lost, so completed cron runs do not become
false audit errors just because the in-memory Gateway runtime state is gone.
Offline CLI audit and maintenance are not authoritative for the Gateway's
process-local cron, CLI, or ACP liveness. They retain active tasks of those
kinds when the local runtime cannot prove completion. Gateway maintenance
marks CLI tasks with a run id/source id lost when their live run context is
gone, even if an old child-session row remains.
When applied, maintenance also prunes cron:<jobId>:run:<uuid> session
registry rows older than 7 days while preserving currently running cron
jobs and leaving non-cron session rows untouched.
flow
openclaw tasks flow list [--status <name>] [--json]
openclaw tasks flow show <lookup> [--json]
openclaw tasks flow cancel <lookup>
Inspects or cancels durable Task Flow state under the task ledger. There is no
top-level openclaw flows command. Both flow show and flow cancel accept a
flow ID or its stable owner key as <lookup>.
flow list --status accepts queued, running, waiting, blocked,
succeeded, failed, cancelled, or lost. See Task Flow
for ownership and lifecycle details.