github/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-19 05:27:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

Channels: add thread-aware model overrides

Browse Source
This commit is contained in:
Shadow
2026-02-20 19:26:25 -06:00
committed by GitHub
parent ee8dd40509
commit f555835b09
53 changed files with 1379 additions and 1398 deletions
Download Patch File Download Diff File Expand all files Collapse all files

43
docs/tools/subagents.md
View File

@@ -35,7 +35,7 @@ Use `/subagents` to inspect or control sub-agent runs for the **current session*
- If direct delivery fails, it falls back to queue routing.
- If queue routing is still not available, the announce is retried with a short exponential backoff before final give-up.
- The completion message is a system message and includes:
- `Result` (latest assistant reply text from the child session, after a short settle retry)
- `Result` (`assistant` reply text, or latest `toolResult` if the assistant reply is empty)
- `Status` (`completed successfully` / `failed` / `timed out`)
- compact runtime/token stats
- `--model` and `--thinking` override defaults for that specific run.
@@ -90,7 +90,7 @@ Auto-archive:
## Nested Sub-Agents
By default, sub-agents can spawn one additional level (`maxSpawnDepth: 2`), enabling the **orchestrator pattern**: main → orchestrator sub-agent → worker sub-sub-agents. Set `maxSpawnDepth: 1` to disable nested spawning.
By default, sub-agents cannot spawn their own sub-agents (`maxSpawnDepth: 1`). You can enable one level of nesting by setting `maxSpawnDepth: 2`, which allows the **orchestrator pattern**: main → orchestrator sub-agent → worker sub-sub-agents.
### How to enable
@@ -99,7 +99,7 @@ By default, sub-agents can spawn one additional level (`maxSpawnDepth: 2`), enab
agents: {
defaults: {
subagents: {
maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 2)
maxSpawnDepth: 2, // allow sub-agents to spawn children (default: 1)
maxChildrenPerAgent: 5, // max active children per agent session (default: 5)
maxConcurrent: 8, // global concurrency lane cap (default: 8)
},
@@ -110,11 +110,11 @@ By default, sub-agents can spawn one additional level (`maxSpawnDepth: 2`), enab
### Depth levels
| Depth | Session key shape | Role | Can spawn? |
| ----- | -------------------------------------------- | ----------------------------------- | ------------------------------ |
| 0 | `agent:<id>:main` | Main agent | Always |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agent (orchestrator by default) | Yes, when `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agent (leaf worker) | No, when `maxSpawnDepth = 2` |
| Depth | Session key shape | Role | Can spawn? |
| ----- | -------------------------------------------- | --------------------------------------------- | ---------------------------- |
| 0 | `agent:<id>:main` | Main agent | Always |
| 1 | `agent:<id>:subagent:<uuid>` | Sub-agent (orchestrator when depth 2 allowed) | Only if `maxSpawnDepth >= 2` |
| 2 | `agent:<id>:subagent:<uuid>:subagent:<uuid>` | Sub-sub-agent (leaf worker) | Never |
### Announce chain
@@ -128,9 +128,9 @@ Each level only sees announces from its direct children.
### Tool policy by depth
- **Depth 1 (orchestrator, default with `maxSpawnDepth = 2`)**: Gets `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` so it can manage its children. Other session/system tools remain denied.
- **Depth 1 (leaf, when `maxSpawnDepth = 1`)**: No session tools.
- **Depth 2 (leaf worker, default `maxSpawnDepth = 2`)**: No session tools, `sessions_spawn` is denied at depth 2, cannot spawn further children.
- **Depth 1 (orchestrator, when `maxSpawnDepth >= 2`)**: Gets `sessions_spawn`, `subagents`, `sessions_list`, `sessions_history` so it can manage its children. Other session/system tools remain denied.
- **Depth 1 (leaf, when `maxSpawnDepth == 1`)**: No session tools (current default behavior).
- **Depth 2 (leaf worker)**: No session tools — `sessions_spawn` is always denied at depth 2. Cannot spawn further children.
### Per-agent spawn limit
@@ -156,16 +156,17 @@ Note: the merge is additive, so main profiles are always available as fallbacks.
## Announce
Sub-agents report back via an announce injection step:
Sub-agents report back via an announce step:
- OpenClaw reads the child session's latest assistant reply after completion, with a short settle retry.
- It builds a system message with `Status`, `Result`, compact stats, and reply guidance.
- The message is injected with a follow-up `agent` call:
- `deliver=false` when the requester is another sub-agent, this keeps orchestration internal.
- `deliver=true` when the requester is main, this produces the user-facing update.
- Delivery context prefers captured requester origin, but non-deliverable channels (for example `webchat`) are ignored in favor of persisted deliverable routes.
- Recipient agents can return the internal silent token to suppress duplicate outward delivery in the same turn.
- `Status` is derived from runtime outcome signals, not inferred from model output.
- The announce step runs inside the sub-agent session (not the requester session).
- If the sub-agent replies exactly `ANNOUNCE_SKIP`, nothing is posted.
- Otherwise the announce reply is posted to the requester chat channel via a follow-up `agent` call (`deliver=true`).
- Announce replies preserve thread/topic routing when available (Slack threads, Telegram topics, Matrix threads).
- Announce messages are normalized to a stable template:
- `Status:` derived from the run outcome (`success`, `error`, `timeout`, or `unknown`).
- `Result:` the summary content from the announce step (or `(not available)` if missing).
- `Notes:` error details and other useful context.
- `Status` is not inferred from model output; it comes from runtime outcome signals.
Announce payloads include a stats line at the end (even when wrapped):
@@ -183,7 +184,7 @@ By default, sub-agents get **all tools except session tools** and system tools:
- `sessions_send`
- `sessions_spawn`
With the default `maxSpawnDepth = 2`, depth-1 orchestrator sub-agents receive `sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they can manage their children. If you set `maxSpawnDepth = 1`, those session tools stay denied.
When `maxSpawnDepth >= 2`, depth-1 orchestrator sub-agents additionally receive `sessions_spawn`, `subagents`, `sessions_list`, and `sessions_history` so they can manage their children.
Override via config: