docs: refresh agent and agents refs

docs/cli/agent.md

@@ -10,20 +10,47 @@ title: "agent"
 Run an agent turn via the Gateway (use `--local` for embedded).
 Use `--agent <id>` to target a configured agent directly.
 
+Pass at least one session selector:
+
+- `--to <dest>`
+- `--session-id <id>`
+- `--agent <id>`
+
 Related:
 
 - Agent send tool: [Agent send](/tools/agent-send)
 
+## Options
+
+- `-m, --message <text>`: required message body
+- `-t, --to <dest>`: recipient used to derive the session key
+- `--session-id <id>`: explicit session id
+- `--agent <id>`: agent id; overrides routing bindings
+- `--thinking <off|minimal|low|medium|high|xhigh>`: agent thinking level
+- `--verbose <on|off>`: persist verbose level for the session
+- `--channel <channel>`: delivery channel; omit to use the main session channel
+- `--reply-to <target>`: delivery target override
+- `--reply-channel <channel>`: delivery channel override
+- `--reply-account <id>`: delivery account override
+- `--local`: run the embedded agent directly
+- `--deliver`: send the reply back to the selected channel/target
+- `--timeout <seconds>`: 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.

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 <channel>`), 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 <dir>`
+- `--model <id>`
+- `--agent-dir <dir>`
+- `--bind <channel[:accountId]>` (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 <id>`
+- `--json`
+
+### `agents bind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--json`
+
+### `agents unbind`
+
+Options:
+
+- `--agent <id>` (defaults to the current default agent)
+- `--bind <channel[:accountId]>` (repeatable)
+- `--all`
+- `--json`
+
+### `agents delete <id>`
+
+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 <id>`
+- `--workspace <dir>`
+- `--identity-file <path>`
+- `--from-identity`
+- `--name <name>`
+- `--theme <theme>`
+- `--emoji <emoji>`
+- `--avatar <value>`
+- `--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

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 <text>`
@@ -840,10 +842,17 @@ Options:
 - `--json`
 - `--timeout <seconds>`
 
+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 <id>`
+- `--agent <id>` (defaults to the current default agent)
 - `--bind <channel[:accountId]>` (repeatable)
 - `--json`
 
@@ -893,11 +903,13 @@ Remove routing bindings for an agent.
 
 Options:
 
-- `--agent <id>`
+- `--agent <id>` (defaults to the current default agent)
 - `--bind <channel[:accountId]>` (repeatable)
 - `--all`
 - `--json`
 
+Use either `--all` or `--bind`, not both.
+
 #### `agents delete <id>`
 
 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 <value>`
 - `--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.