Skip to content

Commit 90a5b08

Browse files
steipetesteipete
committed
docs: add steer command guide
1 parent d57b16f commit 90a5b08

7 files changed

Lines changed: 93 additions & 4 deletions

File tree

‎docs/.i18n/glossary.zh-CN.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -83,6 +83,10 @@
8383
"source": "Steering queue",
8484
"target": "Steering queue"
8585
},
86+
{
87+
"source": "Steer",
88+
"target": "Steer"
89+
},
8690
{
8791
"source": "Models",
8892
"target": "Models"

‎docs/concepts/queue-steering.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,9 @@ Codex review and manual compaction turns reject same-turn steering. When a
4040
runtime cannot accept steering, OpenClaw falls back to the followup queue where
4141
that mode allows it.
4242

43+
This page explains queue-mode steering for normal inbound messages. For the
44+
explicit `/steer <message>` command, see [Steer](/tools/steer).
45+
4346
## Modes
4447

4548
| Mode | Active-run behavior | Later followup behavior |
@@ -86,5 +89,6 @@ sending the batched `turn/steer`.
8689
## Related
8790

8891
- [Command queue](/concepts/queue)
92+
- [Steer](/tools/steer)
8993
- [Messages](/concepts/messages)
9094
- [Agent loop](/concepts/agent-loop)

‎docs/concepts/queue.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,8 @@ streaming surfaces can look like duplicates. Prefer `collect`/`steer` if you wan
5151
one response per inbound message.
5252

5353
For runtime-specific timing and dependency behavior, see
54-
[Steering queue](/concepts/queue-steering).
54+
[Steering queue](/concepts/queue-steering). For the explicit `/steer <message>`
55+
command, see [Steer](/tools/steer).
5556

5657
Configure globally or per channel via `messages.queue`:
5758

@@ -121,4 +122,5 @@ keys.
121122

122123
- [Session management](/concepts/session)
123124
- [Steering queue](/concepts/queue-steering)
125+
- [Steer](/tools/steer)
124126
- [Retry policy](/concepts/retry)

‎docs/docs.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1309,6 +1309,7 @@
13091309
"group": "Agent coordination",
13101310
"pages": [
13111311
"tools/agent-send",
1312+
"tools/steer",
13121313
"tools/subagents",
13131314
"tools/acp-agents",
13141315
"tools/acp-agents-setup",

‎docs/tools/slash-commands.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -145,7 +145,7 @@ Current source-of-truth:
145145
- `/model [name|#|status]` shows or sets the model.
146146
- `/models [provider] [page] [limit=<n>|size=<n>|all]` lists configured/auth-available providers or models for a provider; add `all` to browse that provider's full catalog.
147147
- `/queue <mode>` manages queue behavior (`steer`, legacy `queue`, `followup`, `collect`, `steer-backlog`, `interrupt`) plus options like `debounce:0.5s cap:25 drop:summarize`; `/queue default` or `/queue reset` clears the session override. See [Command queue](/concepts/queue) and [Steering queue](/concepts/queue-steering).
148-
- `/steer <message>` injects guidance into the active run for the current session, independent of `/queue` mode. It does not start a new run when the session is idle. Alias: `/tell`.
148+
- `/steer <message>` injects guidance into the active run for the current session, independent of `/queue` mode. It does not start a new run when the session is idle. Alias: `/tell`. See [Steer](/tools/steer).
149149

150150
</Accordion>
151151
<Accordion title="Discovery and status">
@@ -175,7 +175,7 @@ Current source-of-truth:
175175
- `/unfocus` removes the current binding.
176176
- `/agents` lists thread-bound agents for the current session.
177177
- `/kill <id|#|all>` aborts one or all running sub-agents.
178-
- `/subagents steer <id|#> <message>` sends steering to a running sub-agent.
178+
- `/subagents steer <id|#> <message>` sends steering to a running sub-agent. See [Steer](/tools/steer).
179179

180180
</Accordion>
181181
<Accordion title="Owner-only writes and admin">

‎docs/tools/steer.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
---
2+
summary: "Steer an active run without changing queue mode"
3+
read_when:
4+
- Using /steer or /tell while an agent is already running
5+
- Comparing /steer with /queue steer
6+
- Deciding whether to steer the current run, a sub-agent, or an ACP session
7+
title: "Steer"
8+
sidebarTitle: "Steer"
9+
---
10+
11+
`/steer` sends guidance to an already-active run. It is for "adjust this
12+
run while it is still working" moments, not for starting a new turn.
13+
14+
## Current session
15+
16+
Use top-level `/steer` to target the active run for the current session:
17+
18+
```text
19+
/steer prefer the smaller patch and keep the tests focused
20+
/tell summarize before making the next tool call
21+
```
22+
23+
Behavior:
24+
25+
- Targets only the current session's active run.
26+
- Works independently of the session's `/queue` mode.
27+
- Does not start a new run when the session is idle.
28+
- Replies with a warning when there is no active run to steer.
29+
- Uses the active runtime's steering path, so the model sees the guidance at
30+
the next supported runtime boundary.
31+
32+
## Steer vs queue
33+
34+
`/queue steer` changes how normal inbound messages behave when they arrive
35+
while a run is active. `/steer <message>` is an explicit command that tries to
36+
inject that command's message into the active run at the next supported runtime
37+
boundary, regardless of the stored `/queue` setting.
38+
39+
Use:
40+
41+
- `/steer <message>` when you want to guide the active run right now.
42+
- `/queue steer` when you want future normal messages to steer active runs by
43+
default.
44+
- `/queue collect` or `/queue followup` when new messages should wait for a
45+
later turn instead of steering the active run.
46+
47+
For queue modes and fallback behavior, see [Command queue](/concepts/queue) and
48+
[Steering queue](/concepts/queue-steering).
49+
50+
## Sub-agents
51+
52+
Use `/subagents steer` when the target is a child run:
53+
54+
```text
55+
/subagents steer 2 focus only on the API surface
56+
```
57+
58+
Top-level `/steer` does not select a sub-agent by id or list index. It always
59+
targets the current session's active run. See [Sub-agents](/tools/subagents) for
60+
sub-agent ids, labels, and control commands.
61+
62+
## ACP sessions
63+
64+
Use `/acp steer` when the target is an ACP harness session:
65+
66+
```text
67+
/acp steer --session agent:main:acp:codex tighten the repro
68+
```
69+
70+
See [ACP agents](/tools/acp-agents) for ACP session selection and runtime
71+
behavior.
72+
73+
## Related
74+
75+
- [Slash commands](/tools/slash-commands)
76+
- [Command queue](/concepts/queue)
77+
- [Steering queue](/concepts/queue-steering)
78+
- [Sub-agents](/tools/subagents)

‎docs/tools/subagents.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ session**:
4747
/subagents spawn <agentId> <task> [--model <model>] [--thinking <level>]
4848
```
4949

50-
Use top-level `/steer <message>` to steer the current requester session's active run. Use `/subagents steer <id|#> <message>` when the target is a child run.
50+
Use top-level [`/steer <message>`](/tools/steer) to steer the current requester session's active run. Use `/subagents steer <id|#> <message>` when the target is a child run.
5151

5252
`/subagents info` shows run metadata (status, timestamps, session id,
5353
transcript path, cleanup). Use `sessions_history` for a bounded,

0 commit comments

Comments
 (0)