chore: Run pnpm format:fix.

2026-01-31 19:37:45 +01:00 · 2026-01-31 21:13:13 +09:00
parent dcc2de15a6
commit 8cab78abbc
624 changed files with 10729 additions and 7514 deletions
--- a/docs/tools/index.md
+++ b/docs/tools/index.md
@@ -18,11 +18,12 @@ You can globally allow/deny tools via `tools.allow` / `tools.deny` in `openclaw.

 ```json5
 {
-  tools: { deny: ["browser"] }
+  tools: { deny: ["browser"] },
 }
 ```

 Notes:
+
 - Matching is case-insensitive.
 - `*` wildcards are supported (`"*"` means all tools).
 - If `tools.allow` only references unknown or unloaded plugin tool names, OpenClaw logs a warning and ignores the allowlist so core tools stay available.
@@ -33,32 +34,36 @@ Notes:
 Per-agent override: `agents.list[].tools.profile`.

 Profiles:
+
 - `minimal`: `session_status` only
 - `coding`: `group:fs`, `group:runtime`, `group:sessions`, `group:memory`, `image`
 - `messaging`: `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status`
 - `full`: no restriction (same as unset)

 Example (messaging-only by default, allow Slack + Discord tools too):
+
 ```json5
 {
  tools: {
    profile: "messaging",
-    allow: ["slack", "discord"]
-  }
+    allow: ["slack", "discord"],
+  },
 }
 ```

 Example (coding profile, but deny exec/process everywhere):
+
 ```json5
 {
  tools: {
    profile: "coding",
-    deny: ["group:runtime"]
-  }
+    deny: ["group:runtime"],
+  },
 }
 ```

 Example (global coding profile, messaging-only support agent):
+
 ```json5
 {
  tools: { profile: "coding" },
@@ -66,10 +71,10 @@ Example (global coding profile, messaging-only support agent):
    list: [
      {
        id: "support",
-        tools: { profile: "messaging", allow: ["slack"] }
-      }
-    ]
-  }
+        tools: { profile: "messaging", allow: ["slack"] },
+      },
+    ],
+  },
 }
 ```

@@ -85,30 +90,33 @@ Provider keys accept either `provider` (e.g. `google-antigravity`) or
 `provider/model` (e.g. `openai/gpt-5.2`).

 Example (keep global coding profile, but minimal tools for Google Antigravity):
+
 ```json5
 {
  tools: {
    profile: "coding",
    byProvider: {
-      "google-antigravity": { profile: "minimal" }
-    }
-  }
+      "google-antigravity": { profile: "minimal" },
+    },
+  },
 }
 ```

 Example (provider/model-specific allowlist for a flaky endpoint):
+
 ```json5
 {
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
-      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] }
-    }
-  }
+      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
+    },
+  },
 }
 ```

 Example (agent-specific override for a single provider):
+
 ```json5
 {
  agents: {
@@ -117,12 +125,12 @@ Example (agent-specific override for a single provider):
        id: "support",
        tools: {
          byProvider: {
-            "google-antigravity": { allow: ["message", "sessions_list"] }
-          }
-        }
-      }
-    ]
-  }
+            "google-antigravity": { allow: ["message", "sessions_list"] },
+          },
+        },
+      },
+    ],
+  },
 }
 ```

@@ -132,6 +140,7 @@ Tool policies (global, agent, sandbox) support `group:*` entries that expand to
 Use these in `tools.allow` / `tools.deny`.

 Available groups:
+
 - `group:runtime`: `exec`, `bash`, `process`
 - `group:fs`: `read`, `write`, `edit`, `apply_patch`
 - `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`
@@ -144,11 +153,12 @@ Available groups:
 - `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)

 Example (allow only file tools + browser):
+
 ```json5
 {
  tools: {
-    allow: ["group:fs", "browser"]
-  }
+    allow: ["group:fs", "browser"],
+  },
 }
 ```

@@ -160,19 +170,23 @@ tool usage guidance is injected into prompts. Some plugins ship their own skills
 alongside tools (for example, the voice-call plugin).

 Optional plugin tools:
+
 - [Lobster](/tools/lobster): typed workflow runtime with resumable approvals (requires the Lobster CLI on the gateway host).
 - [LLM Task](/tools/llm-task): JSON-only LLM step for structured workflow output (optional schema validation).

 ## Tool inventory

 ### `apply_patch`
+
 Apply structured patches across one or more files. Use for multi-hunk edits.
 Experimental: enable via `tools.exec.applyPatch.enabled` (OpenAI models only).

 ### `exec`
+
 Run shell commands in the workspace.

 Core parameters:
+
 - `command` (required)
 - `yieldMs` (auto-background after timeout, default 10000)
 - `background` (immediate background)
@@ -185,6 +199,7 @@ Core parameters:
 - Need a real TTY? Set `pty: true`.

 Notes:
+
 - Returns `status: "running"` with a `sessionId` when backgrounded.
 - Use `process` to poll/log/write/kill/clear background sessions.
 - If `process` is disallowed, `exec` runs synchronously and ignores `yieldMs`/`background`.
@@ -194,38 +209,47 @@ Notes:
 - gateway/node approvals and allowlists: [Exec approvals](/tools/exec-approvals).

 ### `process`
+
 Manage background exec sessions.

 Core actions:
+
 - `list`, `poll`, `log`, `write`, `kill`, `clear`, `remove`

 Notes:
+
 - `poll` returns new output and exit status when complete.
 - `log` supports line-based `offset`/`limit` (omit `offset` to grab the last N lines).
 - `process` is scoped per agent; sessions from other agents are not visible.

 ### `web_search`
+
 Search the web using Brave Search API.

 Core parameters:
+
 - `query` (required)
 - `count` (1–10; default from `tools.web.search.maxResults`)

 Notes:
+
 - Requires a Brave API key (recommended: `openclaw configure --section web`, or set `BRAVE_API_KEY`).
 - Enable via `tools.web.search.enabled`.
 - Responses are cached (default 15 min).
 - See [Web tools](/tools/web) for setup.

 ### `web_fetch`
+
 Fetch and extract readable content from a URL (HTML → markdown/text).

 Core parameters:
+
 - `url` (required)
 - `extractMode` (`markdown` | `text`)
 - `maxChars` (truncate long pages)

 Notes:
+
 - Enable via `tools.web.fetch.enabled`.
 - Responses are cached (default 15 min).
 - For JS-heavy sites, prefer the browser tool.
@@ -233,9 +257,11 @@ Notes:
 - See [Firecrawl](/tools/firecrawl) for the optional anti-bot fallback.

 ### `browser`
+
 Control the dedicated OpenClaw-managed browser.

 Core actions:
+
 - `status`, `start`, `stop`, `tabs`, `open`, `focus`, `close`
 - `snapshot` (aria/ai)
 - `screenshot` (returns image block + `MEDIA:<path>`)
@@ -243,16 +269,18 @@ Core actions:
 - `navigate`, `console`, `pdf`, `upload`, `dialog`

 Profile management:
+
 - `profiles` — list all browser profiles with status
 - `create-profile` — create new profile with auto-allocated port (or `cdpUrl`)
 - `delete-profile` — stop browser, delete user data, remove from config (local only)
 - `reset-profile` — kill orphan process on profile's port (local only)

 Common parameters:
+
 - `profile` (optional; defaults to `browser.defaultProfile`)
 - `target` (`sandbox` | `host` | `node`)
 - `node` (optional; picks a specific node id/name)
-Notes:
+  Notes:
 - Requires `browser.enabled=true` (default is `true`; set `false` to disable).
 - All actions accept optional `profile` parameter for multi-instance support.
 - When `profile` is omitted, uses `browser.defaultProfile` (defaults to "chrome").
@@ -268,23 +296,28 @@ Notes:
 - `upload` also supports `inputRef` (aria ref) or `element` (CSS selector) to set `<input type="file">` directly.

 ### `canvas`
+
 Drive the node Canvas (present, eval, snapshot, A2UI).

 Core actions:
+
 - `present`, `hide`, `navigate`, `eval`
 - `snapshot` (returns image block + `MEDIA:<path>`)
 - `a2ui_push`, `a2ui_reset`

 Notes:
+
 - Uses gateway `node.invoke` under the hood.
 - If no `node` is provided, the tool picks a default (single connected node or local mac node).
 - A2UI is v0.8 only (no `createSurface`); the CLI rejects v0.9 JSONL with line errors.
 - Quick smoke: `openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"`.

 ### `nodes`
+
 Discover and target paired nodes; send notifications; capture camera/screen.

 Core actions:
+
 - `status`, `describe`
 - `pending`, `approve`, `reject` (pairing)
 - `notify` (macOS `system.notify`)
@@ -293,6 +326,7 @@ Core actions:
 - `location_get`

 Notes:
+
 - Camera/screen commands require the node app to be foregrounded.
 - Images return image blocks + `MEDIA:<path>`.
 - Videos return `FILE:<path>` (mp4).
@@ -300,6 +334,7 @@ Notes:
 - `run` params: `command` argv array; optional `cwd`, `env` (`KEY=VAL`), `commandTimeoutMs`, `invokeTimeoutMs`, `needsScreenRecording`.

 Example (`run`):
+
 ```json
 {
  "action": "run",
@@ -313,22 +348,27 @@ Example (`run`):
 ```

 ### `image`
+
 Analyze an image with the configured image model.

 Core parameters:
+
 - `image` (required path or URL)
 - `prompt` (optional; defaults to "Describe the image.")
 - `model` (optional override)
 - `maxBytesMb` (optional size cap)

 Notes:
+
 - Only available when `agents.defaults.imageModel` is configured (primary or fallbacks), or when an implicit image model can be inferred from your default model + configured auth (best-effort pairing).
 - Uses the image model directly (independent of the main chat model).

 ### `message`
+
 Send messages and channel actions across Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/iMessage/MS Teams.

 Core actions:
+
 - `send` (text + optional media; MS Teams also supports `card` for Adaptive Cards)
 - `poll` (WhatsApp/Discord/MS Teams polls)
 - `react` / `reactions` / `read` / `edit` / `delete`
@@ -346,26 +386,32 @@ Core actions:
 - `timeout` / `kick` / `ban`

 Notes:
+
 - `send` routes WhatsApp via the Gateway; other channels go direct.
 - `poll` uses the Gateway for WhatsApp and MS Teams; Discord polls go direct.
 - When a message tool call is bound to an active chat session, sends are constrained to that session’s target to avoid cross-context leaks.

 ### `cron`
+
 Manage Gateway cron jobs and wakeups.

 Core actions:
+
 - `status`, `list`
 - `add`, `update`, `remove`, `run`, `runs`
 - `wake` (enqueue system event + optional immediate heartbeat)

 Notes:
+
 - `add` expects a full cron job object (same schema as `cron.add` RPC).
 - `update` uses `{ id, patch }`.

 ### `gateway`
+
 Restart or apply updates to the running Gateway process (in-place).

 Core actions:
+
 - `restart` (authorizes + sends `SIGUSR1` for in-process restart; `openclaw gateway` restart in-place)
 - `config.get` / `config.schema`
 - `config.apply` (validate + write config + restart + wake)
@@ -373,13 +419,16 @@ Core actions:
 - `update.run` (run update + restart + wake)

 Notes:
+
 - Use `delayMs` (defaults to 2000) to avoid interrupting an in-flight reply.
 - `restart` is disabled by default; enable with `commands.restart: true`.

 ### `sessions_list` / `sessions_history` / `sessions_send` / `sessions_spawn` / `session_status`
+
 List sessions, inspect transcript history, or send to another session.

 Core parameters:
+
 - `sessions_list`: `kinds?`, `limit?`, `activeMinutes?`, `messageLimit?` (0 = none)
 - `sessions_history`: `sessionKey` (or `sessionId`), `limit?`, `includeTools?`
 - `sessions_send`: `sessionKey` (or `sessionId`), `message`, `timeoutSeconds?` (0 = fire-and-forget)
@@ -387,6 +436,7 @@ Core parameters:
 - `session_status`: `sessionKey?` (default current; accepts `sessionId`), `model?` (`default` clears override)

 Notes:
+
 - `main` is the canonical direct-chat key; global/unknown are hidden.
 - `messageLimit > 0` fetches last N messages per session (tool messages filtered).
 - `sessions_send` waits for final completion when `timeoutSeconds > 0`.
@@ -397,20 +447,24 @@ Notes:
 - After the ping‑pong, the target agent runs an **announce step**; reply `ANNOUNCE_SKIP` to suppress the announcement.

 ### `agents_list`
+
 List agent ids that the current session may target with `sessions_spawn`.

 Notes:
+
 - Result is restricted to per-agent allowlists (`agents.list[].subagents.allowAgents`).
 - When `["*"]` is configured, the tool includes all configured agents and marks `allowAny: true`.

 ## Parameters (common)

 Gateway-backed tools (`canvas`, `nodes`, `cron`):
+
 - `gatewayUrl` (default `ws://127.0.0.1:18789`)
 - `gatewayToken` (if auth enabled)
 - `timeoutMs`

 Browser tool:
+
 - `profile` (optional; defaults to `browser.defaultProfile`)
 - `target` (`sandbox` | `host` | `node`)
 - `node` (optional; pin a specific node id/name)
@@ -418,20 +472,23 @@ Browser tool:
 ## Recommended agent flows

 Browser automation:
-1) `browser` → `status` / `start`
-2) `snapshot` (ai or aria)
-3) `act` (click/type/press)
-4) `screenshot` if you need visual confirmation
+
+1. `browser` → `status` / `start`
+2. `snapshot` (ai or aria)
+3. `act` (click/type/press)
+4. `screenshot` if you need visual confirmation

 Canvas render:
-1) `canvas` → `present`
-2) `a2ui_push` (optional)
-3) `snapshot`
+
+1. `canvas` → `present`
+2. `a2ui_push` (optional)
+3. `snapshot`

 Node targeting:
-1) `nodes` → `status`
-2) `describe` on the chosen node
-3) `notify` / `run` / `camera_snap` / `screen_record`
+
+1. `nodes` → `status`
+2. `describe` on the chosen node
+3. `notify` / `run` / `camera_snap` / `screen_record`

 ## Safety

@@ -443,8 +500,8 @@ Node targeting:

 Tools are exposed in two parallel channels:

-1) **System prompt text**: a human-readable list + guidance.
-2) **Tool schema**: the structured function definitions sent to the model API.
+1. **System prompt text**: a human-readable list + guidance.
+2. **Tool schema**: the structured function definitions sent to the model API.

 That means the agent sees both “what tools exist” and “how to call them.” If a tool
 doesn’t appear in the system prompt or the schema, the model cannot call it.