From 3967ffec2262b665430821b3b89b2d2d356ade2c Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Sat, 4 Apr 2026 08:42:43 +0100 Subject: [PATCH] docs: refresh agent and agents refs --- docs/cli/agent.md | 27 ++++++++++++++ docs/cli/agents.md | 91 ++++++++++++++++++++++++++++++++++++++++++++++ docs/cli/index.md | 26 ++++++++++++- 3 files changed, 142 insertions(+), 2 deletions(-) diff --git a/docs/cli/agent.md b/docs/cli/agent.md index 430bdf50743..06da3ec406c 100644 --- a/docs/cli/agent.md +++ b/docs/cli/agent.md @@ -10,20 +10,47 @@ title: "agent" Run an agent turn via the Gateway (use `--local` for embedded). Use `--agent ` to target a configured agent directly. +Pass at least one session selector: + +- `--to ` +- `--session-id ` +- `--agent ` + Related: - Agent send tool: [Agent send](/tools/agent-send) +## Options + +- `-m, --message `: required message body +- `-t, --to `: recipient used to derive the session key +- `--session-id `: explicit session id +- `--agent `: agent id; overrides routing bindings +- `--thinking `: agent thinking level +- `--verbose `: persist verbose level for the session +- `--channel `: delivery channel; omit to use the main session channel +- `--reply-to `: delivery target override +- `--reply-channel `: delivery channel override +- `--reply-account `: delivery account override +- `--local`: run the embedded agent directly +- `--deliver`: send the reply back to the selected channel/target +- `--timeout `: override agent timeout (default 600 or config value) +- `--json`: output JSON + ## Examples ```bash openclaw agent --to +15555550123 --message "status update" --deliver openclaw agent --agent ops --message "Summarize logs" openclaw agent --session-id 1234 --message "Summarize inbox" --thinking medium +openclaw agent --to +15555550123 --message "Trace logs" --verbose on --json openclaw agent --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports" +openclaw agent --agent ops --message "Run locally" --local ``` ## Notes +- Gateway mode falls back to the embedded agent when the Gateway request fails. Use `--local` to force embedded execution up front. +- `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not session routing. - When this command triggers `models.json` regeneration, SecretRef-managed provider credentials are persisted as non-secret markers (for example env var names, `secretref-env:ENV_VAR_NAME`, or `secretref-managed`), not resolved secret plaintext. - Marker writes are source-authoritative: OpenClaw persists markers from the active source config snapshot, not from resolved runtime secret values. diff --git a/docs/cli/agents.md b/docs/cli/agents.md index 320b7f1e136..7110732338e 100644 --- a/docs/cli/agents.md +++ b/docs/cli/agents.md @@ -19,7 +19,9 @@ Related: ```bash openclaw agents list +openclaw agents list --bindings openclaw agents add work --workspace ~/.openclaw/workspace-work +openclaw agents add ops --workspace ~/.openclaw/workspace-ops --bind telegram:ops --non-interactive openclaw agents bindings openclaw agents bind --agent work --bind telegram:ops openclaw agents unbind --agent work --bind telegram:ops @@ -53,6 +55,8 @@ openclaw agents bind --agent work --bind telegram:ops --bind discord:guild-a If you omit `accountId` (`--bind `), OpenClaw resolves it from channel defaults and plugin setup hooks when available. +If you omit `--agent` for `bind` or `unbind`, OpenClaw targets the current default agent. + ### Binding scope behavior - A binding without `accountId` matches the channel default account only. @@ -78,6 +82,75 @@ openclaw agents unbind --agent work --bind telegram:ops openclaw agents unbind --agent work --all ``` +`unbind` accepts either `--all` or one or more `--bind` values, not both. + +## Command surface + +### `agents` + +Running `openclaw agents` with no subcommand is equivalent to `openclaw agents list`. + +### `agents list` + +Options: + +- `--json` +- `--bindings`: include full routing rules, not only per-agent counts/summaries + +### `agents add [name]` + +Options: + +- `--workspace ` +- `--model ` +- `--agent-dir ` +- `--bind ` (repeatable) +- `--non-interactive` +- `--json` + +Notes: + +- Passing any explicit add flags switches the command into the non-interactive path. +- Non-interactive mode requires both an agent name and `--workspace`. +- `main` is reserved and cannot be used as the new agent id. + +### `agents bindings` + +Options: + +- `--agent ` +- `--json` + +### `agents bind` + +Options: + +- `--agent ` (defaults to the current default agent) +- `--bind ` (repeatable) +- `--json` + +### `agents unbind` + +Options: + +- `--agent ` (defaults to the current default agent) +- `--bind ` (repeatable) +- `--all` +- `--json` + +### `agents delete ` + +Options: + +- `--force` +- `--json` + +Notes: + +- `main` cannot be deleted. +- Without `--force`, interactive confirmation is required. +- Workspace, agent state, and session transcript directories are moved to Trash, not hard-deleted. + ## Identity files Each agent workspace can include an `IDENTITY.md` at the workspace root: @@ -96,6 +169,24 @@ Avatar paths resolve relative to the workspace root. - `emoji` - `avatar` (workspace-relative path, http(s) URL, or data URI) +Options: + +- `--agent ` +- `--workspace ` +- `--identity-file ` +- `--from-identity` +- `--name ` +- `--theme ` +- `--emoji ` +- `--avatar ` +- `--json` + +Notes: + +- `--agent` or `--workspace` can be used to select the target agent. +- If you rely on `--workspace` and multiple agents share that workspace, the command fails and asks you to pass `--agent`. +- When no explicit identity fields are provided, the command reads identity data from `IDENTITY.md`. + Load from `IDENTITY.md`: ```bash diff --git a/docs/cli/index.md b/docs/cli/index.md index 2b34fe37c55..cee7469edc8 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -820,6 +820,8 @@ Examples: Run one agent turn via the Gateway (or `--local` embedded). +Pass at least one session selector: `--to`, `--session-id`, or `--agent`. + Required: - `-m, --message ` @@ -840,10 +842,17 @@ Options: - `--json` - `--timeout ` +Notes: + +- Gateway mode falls back to the embedded agent when the Gateway request fails. +- `--channel`, `--reply-channel`, and `--reply-account` affect reply delivery, not routing. + ### `agents` Manage isolated agents (workspaces + auth + routing). +Running `openclaw agents` with no subcommand is equivalent to `openclaw agents list`. + #### `agents list` List configured agents. @@ -867,6 +876,7 @@ Options: - `--json` Binding specs use `channel[:accountId]`. When `accountId` is omitted, OpenClaw may resolve account scope via channel defaults/plugin hooks; otherwise it is a channel binding without explicit account scope. +Passing any explicit add flags switches the command into the non-interactive path. `main` is reserved and cannot be used as the new agent id. #### `agents bindings` @@ -883,7 +893,7 @@ Add routing bindings for an agent. Options: -- `--agent ` +- `--agent ` (defaults to the current default agent) - `--bind ` (repeatable) - `--json` @@ -893,11 +903,13 @@ Remove routing bindings for an agent. Options: -- `--agent ` +- `--agent ` (defaults to the current default agent) - `--bind ` (repeatable) - `--all` - `--json` +Use either `--all` or `--bind`, not both. + #### `agents delete ` Delete an agent and prune its workspace + state. @@ -907,6 +919,11 @@ Options: - `--force` - `--json` +Notes: + +- `main` cannot be deleted. +- Without `--force`, interactive confirmation is required. + #### `agents set-identity` Update an agent identity (name/theme/emoji/avatar). @@ -923,6 +940,11 @@ Options: - `--avatar ` - `--json` +Notes: + +- `--agent` or `--workspace` can be used to select the target agent. +- When no explicit identity fields are provided, the command reads `IDENTITY.md`. + ### `acp` Run the ACP bridge that connects IDEs to the Gateway.