From ae0e1ecf5c863d94fa201f572b07cb2945012d52 Mon Sep 17 00:00:00 2001 From: Vincent Koc Date: Mon, 30 Mar 2026 16:42:47 +0900 Subject: [PATCH] docs: add background tasks cross-references across 6 doc pages Link to /automation/tasks from all pages that mention subagent runs, ACP runs, or detached background work: - tools/subagents.md: note that each sub-agent run is tracked as a background task - tools/acp-agents.md: note that ACP session spawns are tracked as background tasks - cli/index.md: link tasks section to doc page, add tasks audit subcommand - concepts/queue.md: note that detached lane runs are tracked as background tasks - gateway/configuration-reference.md: cron section cross-ref to tasks - help/faq.md: add tasks link to sub-agent offloading FAQ answer --- docs/cli/index.md | 5 +++-- docs/concepts/queue.md | 2 +- docs/gateway/configuration-reference.md | 2 +- docs/help/faq.md | 2 +- docs/tools/acp-agents.md | 2 +- docs/tools/subagents.md | 2 +- 6 files changed, 8 insertions(+), 7 deletions(-) diff --git a/docs/cli/index.md b/docs/cli/index.md index 9edd8fd17e7..a07fb449ee3 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -801,12 +801,13 @@ Notes: ### `tasks` -List and manage task runs across agents. +List and manage [background task](/automation/tasks) runs across agents. - `tasks list` — show active and recent task runs - `tasks show ` — show details for a specific task run -- `tasks notify ` — send a notification for a task run +- `tasks notify ` — change notification policy for a task run - `tasks cancel ` — cancel a running task +- `tasks audit` — surface operational issues (stale, lost, delivery failures) ## Gateway diff --git a/docs/concepts/queue.md b/docs/concepts/queue.md index 65ae799da0a..701fb9aaf46 100644 --- a/docs/concepts/queue.md +++ b/docs/concepts/queue.md @@ -79,7 +79,7 @@ Defaults: `debounceMs: 1000`, `cap: 20`, `drop: summarize`. - Applies to auto-reply agent runs across all inbound channels that use the gateway reply pipeline (WhatsApp web, Telegram, Slack, Discord, Signal, iMessage, webchat, etc.). - Default lane (`main`) is process-wide for inbound + main heartbeats; set `agents.defaults.maxConcurrent` to allow multiple sessions in parallel. -- Additional lanes may exist (e.g. `cron`, `subagent`) so background jobs can run in parallel without blocking inbound replies. +- Additional lanes may exist (e.g. `cron`, `subagent`) so background jobs can run in parallel without blocking inbound replies. These detached runs are tracked as [background tasks](/automation/tasks). - Per-session lanes guarantee that only one agent run touches a given session at a time. - No external dependencies or background worker threads; pure TypeScript + promises. diff --git a/docs/gateway/configuration-reference.md b/docs/gateway/configuration-reference.md index 2e0f9b0d78a..8921e68b6d1 100644 --- a/docs/gateway/configuration-reference.md +++ b/docs/gateway/configuration-reference.md @@ -3316,7 +3316,7 @@ Applies only to one-shot cron jobs. Recurring jobs use separate failure handling - `mode`: delivery mode — `"announce"` sends via a channel message; `"webhook"` posts to the configured webhook. - `accountId`: optional account or channel id to scope alert delivery. -See [Cron Jobs](/automation/cron-jobs). +See [Cron Jobs](/automation/cron-jobs). Isolated cron executions are tracked as [background tasks](/automation/tasks). --- diff --git a/docs/help/faq.md b/docs/help/faq.md index aa8d88dfa67..d4f04d87939 100644 --- a/docs/help/faq.md +++ b/docs/help/faq.md @@ -952,7 +952,7 @@ for usage/billing and raise limits as needed. Token tip: long tasks and sub-agents both consume tokens. If cost is a concern, set a cheaper model for sub-agents via `agents.defaults.subagents.model`. - Docs: [Sub-agents](/tools/subagents). + Docs: [Sub-agents](/tools/subagents), [Background Tasks](/automation/tasks). diff --git a/docs/tools/acp-agents.md b/docs/tools/acp-agents.md index 926ca6d75e9..ae7d34cd220 100644 --- a/docs/tools/acp-agents.md +++ b/docs/tools/acp-agents.md @@ -13,7 +13,7 @@ title: "ACP Agents" [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) sessions let OpenClaw run external coding harnesses (for example Pi, Claude Code, Codex, Cursor, Copilot, OpenClaw ACP, OpenCode, Gemini CLI, and other supported ACPX harnesses) through an ACP backend plugin. -If you ask OpenClaw in plain language to "run this in Codex" or "start Claude Code in a thread", OpenClaw should route that request to the ACP runtime (not the native sub-agent runtime). +If you ask OpenClaw in plain language to "run this in Codex" or "start Claude Code in a thread", OpenClaw should route that request to the ACP runtime (not the native sub-agent runtime). Each ACP session spawn is tracked as a [background task](/automation/tasks). If you want Codex or Claude Code to connect as an external MCP client directly to existing OpenClaw channel conversations, use [`openclaw mcp serve`](/cli/mcp) diff --git a/docs/tools/subagents.md b/docs/tools/subagents.md index dabfc91dfc2..8d3c876ceeb 100644 --- a/docs/tools/subagents.md +++ b/docs/tools/subagents.md @@ -9,7 +9,7 @@ title: "Sub-Agents" # Sub-agents -Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent::subagent:`) and, when finished, **announce** their result back to the requester chat channel. +Sub-agents are background agent runs spawned from an existing agent run. They run in their own session (`agent::subagent:`) and, when finished, **announce** their result back to the requester chat channel. Each sub-agent run is tracked as a [background task](/automation/tasks). ## Slash command