@captain-app/openclaw 2026.2.4

package/docs/channels/zalouser.md

@@ -0,0 +1,140 @@
+---
+summary: "Zalo personal account support via zca-cli (QR login), capabilities, and configuration"
+read_when:
+  - Setting up Zalo Personal for OpenClaw
+  - Debugging Zalo Personal login or message flow
+title: "Zalo Personal"
+---
+
+# Zalo Personal (unofficial)
+
+Status: experimental. This integration automates a **personal Zalo account** via `zca-cli`.
+
+> **Warning:** This is an unofficial integration and may result in account suspension/ban. Use at your own risk.
+
+## Plugin required
+
+Zalo Personal ships as a plugin and is not bundled with the core install.
+
+- Install via CLI: `openclaw plugins install @openclaw/zalouser`
+- Or from a source checkout: `openclaw plugins install ./extensions/zalouser`
+- Details: [Plugins](/plugin)
+
+## Prerequisite: zca-cli
+
+The Gateway machine must have the `zca` binary available in `PATH`.
+
+- Verify: `zca --version`
+- If missing, install zca-cli (see `extensions/zalouser/README.md` or the upstream zca-cli docs).
+
+## Quick setup (beginner)
+
+1. Install the plugin (see above).
+2. Login (QR, on the Gateway machine):
+   - `openclaw channels login --channel zalouser`
+   - Scan the QR code in the terminal with the Zalo mobile app.
+3. Enable the channel:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      dmPolicy: "pairing",
+    },
+  },
+}
+```
+
+4. Restart the Gateway (or finish onboarding).
+5. DM access defaults to pairing; approve the pairing code on first contact.
+
+## What it is
+
+- Uses `zca listen` to receive inbound messages.
+- Uses `zca msg ...` to send replies (text/media/link).
+- Designed for “personal account” use cases where Zalo Bot API is not available.
+
+## Naming
+
+Channel id is `zalouser` to make it explicit this automates a **personal Zalo user account** (unofficial). We keep `zalo` reserved for a potential future official Zalo API integration.
+
+## Finding IDs (directory)
+
+Use the directory CLI to discover peers/groups and their IDs:
+
+```bash
+openclaw directory self --channel zalouser
+openclaw directory peers list --channel zalouser --query "name"
+openclaw directory groups list --channel zalouser --query "work"
+```
+
+## Limits
+
+- Outbound text is chunked to ~2000 characters (Zalo client limits).
+- Streaming is blocked by default.
+
+## Access control (DMs)
+
+`channels.zalouser.dmPolicy` supports: `pairing | allowlist | open | disabled` (default: `pairing`).
+`channels.zalouser.allowFrom` accepts user IDs or names. The wizard resolves names to IDs via `zca friend find` when available.
+
+Approve via:
+
+- `openclaw pairing list zalouser`
+- `openclaw pairing approve zalouser <code>`
+
+## Group access (optional)
+
+- Default: `channels.zalouser.groupPolicy = "open"` (groups allowed). Use `channels.defaults.groupPolicy` to override the default when unset.
+- Restrict to an allowlist with:
+  - `channels.zalouser.groupPolicy = "allowlist"`
+  - `channels.zalouser.groups` (keys are group IDs or names)
+- Block all groups: `channels.zalouser.groupPolicy = "disabled"`.
+- The configure wizard can prompt for group allowlists.
+- On startup, OpenClaw resolves group/user names in allowlists to IDs and logs the mapping; unresolved entries are kept as typed.
+
+Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      groupPolicy: "allowlist",
+      groups: {
+        "123456789": { allow: true },
+        "Work Chat": { allow: true },
+      },
+    },
+  },
+}
+```
+
+## Multi-account
+
+Accounts map to zca profiles. Example:
+
+```json5
+{
+  channels: {
+    zalouser: {
+      enabled: true,
+      defaultAccount: "default",
+      accounts: {
+        work: { enabled: true, profile: "work" },
+      },
+    },
+  },
+}
+```
+
+## Troubleshooting
+
+**`zca` not found:**
+
+- Install zca-cli and ensure it’s on `PATH` for the Gateway process.
+
+**Login doesn’t stick:**
+
+- `openclaw channels status --probe`
+- Re-login: `openclaw channels logout --channel zalouser && openclaw channels login --channel zalouser`

package/docs/cli/acp.md

@@ -0,0 +1,170 @@
+---
+summary: "Run the ACP bridge for IDE integrations"
+read_when:
+  - Setting up ACP-based IDE integrations
+  - Debugging ACP session routing to the Gateway
+title: "acp"
+---
+
+# acp
+
+Run the ACP (Agent Client Protocol) bridge that talks to a OpenClaw Gateway.
+
+This command speaks ACP over stdio for IDEs and forwards prompts to the Gateway
+over WebSocket. It keeps ACP sessions mapped to Gateway session keys.
+
+## Usage
+
+```bash
+openclaw acp
+
+# Remote Gateway
+openclaw acp --url wss://gateway-host:18789 --token <token>
+
+# Attach to an existing session key
+openclaw acp --session agent:main:main
+
+# Attach by label (must already exist)
+openclaw acp --session-label "support inbox"
+
+# Reset the session key before the first prompt
+openclaw acp --session agent:main:main --reset-session
+```
+
+## ACP client (debug)
+
+Use the built-in ACP client to sanity-check the bridge without an IDE.
+It spawns the ACP bridge and lets you type prompts interactively.
+
+```bash
+openclaw acp client
+
+# Point the spawned bridge at a remote Gateway
+openclaw acp client --server-args --url wss://gateway-host:18789 --token <token>
+
+# Override the server command (default: openclaw)
+openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
+```
+
+## How to use this
+
+Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
+it to drive a OpenClaw Gateway session.
+
+1. Ensure the Gateway is running (local or remote).
+2. Configure the Gateway target (config or flags).
+3. Point your IDE to run `openclaw acp` over stdio.
+
+Example config (persisted):
+
+```bash
+openclaw config set gateway.remote.url wss://gateway-host:18789
+openclaw config set gateway.remote.token <token>
+```
+
+Example direct run (no config write):
+
+```bash
+openclaw acp --url wss://gateway-host:18789 --token <token>
+```
+
+## Selecting agents
+
+ACP does not pick agents directly. It routes by the Gateway session key.
+
+Use agent-scoped session keys to target a specific agent:
+
+```bash
+openclaw acp --session agent:main:main
+openclaw acp --session agent:design:main
+openclaw acp --session agent:qa:bug-123
+```
+
+Each ACP session maps to a single Gateway session key. One agent can have many
+sessions; ACP defaults to an isolated `acp:<uuid>` session unless you override
+the key or label.
+
+## Zed editor setup
+
+Add a custom ACP agent in `~/.config/zed/settings.json` (or use Zed’s Settings UI):
+
+```json
+{
+  "agent_servers": {
+    "OpenClaw ACP": {
+      "type": "custom",
+      "command": "openclaw",
+      "args": ["acp"],
+      "env": {}
+    }
+  }
+}
+```
+
+To target a specific Gateway or agent:
+
+```json
+{
+  "agent_servers": {
+    "OpenClaw ACP": {
+      "type": "custom",
+      "command": "openclaw",
+      "args": [
+        "acp",
+        "--url",
+        "wss://gateway-host:18789",
+        "--token",
+        "<token>",
+        "--session",
+        "agent:design:main"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+In Zed, open the Agent panel and select “OpenClaw ACP” to start a thread.
+
+## Session mapping
+
+By default, ACP sessions get an isolated Gateway session key with an `acp:` prefix.
+To reuse a known session, pass a session key or label:
+
+- `--session <key>`: use a specific Gateway session key.
+- `--session-label <label>`: resolve an existing session by label.
+- `--reset-session`: mint a fresh session id for that key (same key, new transcript).
+
+If your ACP client supports metadata, you can override per session:
+
+```json
+{
+  "_meta": {
+    "sessionKey": "agent:main:main",
+    "sessionLabel": "support inbox",
+    "resetSession": true
+  }
+}
+```
+
+Learn more about session keys at [/concepts/session](/concepts/session).
+
+## Options
+
+- `--url <url>`: Gateway WebSocket URL (defaults to gateway.remote.url when configured).
+- `--token <token>`: Gateway auth token.
+- `--password <password>`: Gateway auth password.
+- `--session <key>`: default session key.
+- `--session-label <label>`: default session label to resolve.
+- `--require-existing`: fail if the session key/label does not exist.
+- `--reset-session`: reset the session key before first use.
+- `--no-prefix-cwd`: do not prefix prompts with the working directory.
+- `--verbose, -v`: verbose logging to stderr.
+
+### `acp client` options
+
+- `--cwd <dir>`: working directory for the ACP session.
+- `--server <command>`: ACP server command (default: `openclaw`).
+- `--server-args <args...>`: extra arguments passed to the ACP server.
+- `--server-verbose`: enable verbose logging on the ACP server.
+- `--verbose, -v`: verbose client logging.

package/docs/cli/agent.md

@@ -0,0 +1,24 @@
+---
+summary: "CLI reference for `openclaw agent` (send one agent turn via the Gateway)"
+read_when:
+  - You want to run one agent turn from scripts (optionally deliver reply)
+title: "agent"
+---
+
+# `openclaw agent`
+
+Run an agent turn via the Gateway (use `--local` for embedded).
+Use `--agent <id>` to target a configured agent directly.
+
+Related:
+
+- Agent send tool: [Agent send](/tools/agent-send)
+
+## 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 --agent ops --message "Generate report" --deliver --reply-channel slack --reply-to "#reports"
+```

package/docs/cli/agents.md

@@ -0,0 +1,75 @@
+---
+summary: "CLI reference for `openclaw agents` (list/add/delete/set identity)"
+read_when:
+  - You want multiple isolated agents (workspaces + routing + auth)
+title: "agents"
+---
+
+# `openclaw agents`
+
+Manage isolated agents (workspaces + auth + routing).
+
+Related:
+
+- Multi-agent routing: [Multi-Agent Routing](/concepts/multi-agent)
+- Agent workspace: [Agent workspace](/concepts/agent-workspace)
+
+## Examples
+
+```bash
+openclaw agents list
+openclaw agents add work --workspace ~/.openclaw/workspace-work
+openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
+openclaw agents set-identity --agent main --avatar avatars/openclaw.png
+openclaw agents delete work
+```
+
+## Identity files
+
+Each agent workspace can include an `IDENTITY.md` at the workspace root:
+
+- Example path: `~/.openclaw/workspace/IDENTITY.md`
+- `set-identity --from-identity` reads from the workspace root (or an explicit `--identity-file`)
+
+Avatar paths resolve relative to the workspace root.
+
+## Set identity
+
+`set-identity` writes fields into `agents.list[].identity`:
+
+- `name`
+- `theme`
+- `emoji`
+- `avatar` (workspace-relative path, http(s) URL, or data URI)
+
+Load from `IDENTITY.md`:
+
+```bash
+openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
+```
+
+Override fields explicitly:
+
+```bash
+openclaw agents set-identity --agent main --name "OpenClaw" --emoji "🦞" --avatar avatars/openclaw.png
+```
+
+Config sample:
+
+```json5
+{
+  agents: {
+    list: [
+      {
+        id: "main",
+        identity: {
+          name: "OpenClaw",
+          theme: "space lobster",
+          emoji: "🦞",
+          avatar: "avatars/openclaw.png",
+        },
+      },
+    ],
+  },
+}
+```

package/docs/cli/approvals.md

@@ -0,0 +1,50 @@
+---
+summary: "CLI reference for `openclaw approvals` (exec approvals for gateway or node hosts)"
+read_when:
+  - You want to edit exec approvals from the CLI
+  - You need to manage allowlists on gateway or node hosts
+title: "approvals"
+---
+
+# `openclaw approvals`
+
+Manage exec approvals for the **local host**, **gateway host**, or a **node host**.
+By default, commands target the local approvals file on disk. Use `--gateway` to target the gateway, or `--node` to target a specific node.
+
+Related:
+
+- Exec approvals: [Exec approvals](/tools/exec-approvals)
+- Nodes: [Nodes](/nodes)
+
+## Common commands
+
+```bash
+openclaw approvals get
+openclaw approvals get --node <id|name|ip>
+openclaw approvals get --gateway
+```
+
+## Replace approvals from a file
+
+```bash
+openclaw approvals set --file ./exec-approvals.json
+openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
+openclaw approvals set --gateway --file ./exec-approvals.json
+```
+
+## Allowlist helpers
+
+```bash
+openclaw approvals allowlist add "~/Projects/**/bin/rg"
+openclaw approvals allowlist add --agent main --node <id|name|ip> "/usr/bin/uptime"
+openclaw approvals allowlist add --agent "*" "/usr/bin/uname"
+
+openclaw approvals allowlist remove "~/Projects/**/bin/rg"
+```
+
+## Notes
+
+- `--node` uses the same resolver as `openclaw nodes` (id, name, ip, or id prefix).
+- `--agent` defaults to `"*"`, which applies to all agents.
+- The node host must advertise `system.execApprovals.get/set` (macOS app or headless node host).
+- Approvals files are stored per host at `~/.openclaw/exec-approvals.json`.

package/docs/cli/browser.md

@@ -0,0 +1,107 @@
+---
+summary: "CLI reference for `openclaw browser` (profiles, tabs, actions, extension relay)"
+read_when:
+  - You use `openclaw browser` and want examples for common tasks
+  - You want to control a browser running on another machine via a node host
+  - You want to use the Chrome extension relay (attach/detach via toolbar button)
+title: "browser"
+---
+
+# `openclaw browser`
+
+Manage OpenClaw’s browser control server and run browser actions (tabs, snapshots, screenshots, navigation, clicks, typing).
+
+Related:
+
+- Browser tool + API: [Browser tool](/tools/browser)
+- Chrome extension relay: [Chrome extension](/tools/chrome-extension)
+
+## Common flags
+
+- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
+- `--token <token>`: Gateway token (if required).
+- `--timeout <ms>`: request timeout (ms).
+- `--browser-profile <name>`: choose a browser profile (default from config).
+- `--json`: machine-readable output (where supported).
+
+## Quick start (local)
+
+```bash
+openclaw browser --browser-profile chrome tabs
+openclaw browser --browser-profile openclaw start
+openclaw browser --browser-profile openclaw open https://example.com
+openclaw browser --browser-profile openclaw snapshot
+```
+
+## Profiles
+
+Profiles are named browser routing configs. In practice:
+
+- `openclaw`: launches/attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
+- `chrome`: controls your existing Chrome tab(s) via the Chrome extension relay.
+
+```bash
+openclaw browser profiles
+openclaw browser create-profile --name work --color "#FF5A36"
+openclaw browser delete-profile --name work
+```
+
+Use a specific profile:
+
+```bash
+openclaw browser --browser-profile work tabs
+```
+
+## Tabs
+
+```bash
+openclaw browser tabs
+openclaw browser open https://docs.openclaw.ai
+openclaw browser focus <targetId>
+openclaw browser close <targetId>
+```
+
+## Snapshot / screenshot / actions
+
+Snapshot:
+
+```bash
+openclaw browser snapshot
+```
+
+Screenshot:
+
+```bash
+openclaw browser screenshot
+```
+
+Navigate/click/type (ref-based UI automation):
+
+```bash
+openclaw browser navigate https://example.com
+openclaw browser click <ref>
+openclaw browser type <ref> "hello"
+```
+
+## Chrome extension relay (attach via toolbar button)
+
+This mode lets the agent control an existing Chrome tab that you attach manually (it does not auto-attach).
+
+Install the unpacked extension to a stable path:
+
+```bash
+openclaw browser extension install
+openclaw browser extension path
+```
+
+Then Chrome → `chrome://extensions` → enable “Developer mode” → “Load unpacked” → select the printed folder.
+
+Full guide: [Chrome extension](/tools/chrome-extension)
+
+## Remote browser control (node host proxy)
+
+If the Gateway runs on a different machine than the browser, run a **node host** on the machine that has Chrome/Brave/Edge/Chromium. The Gateway will proxy browser actions to that node (no separate browser control server required).
+
+Use `gateway.nodes.browser.mode` to control auto-routing and `gateway.nodes.browser.node` to pin a specific node if multiple are connected.
+
+Security + remote setup: [Browser tool](/tools/browser), [Remote access](/gateway/remote), [Tailscale](/gateway/tailscale), [Security](/gateway/security)

package/docs/cli/channels.md

@@ -0,0 +1,79 @@
+---
+summary: "CLI reference for `openclaw channels` (accounts, status, login/logout, logs)"
+read_when:
+  - You want to add/remove channel accounts (WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage)
+  - You want to check channel status or tail channel logs
+title: "channels"
+---
+
+# `openclaw channels`
+
+Manage chat channel accounts and their runtime status on the Gateway.
+
+Related docs:
+
+- Channel guides: [Channels](/channels/index)
+- Gateway configuration: [Configuration](/gateway/configuration)
+
+## Common commands
+
+```bash
+openclaw channels list
+openclaw channels status
+openclaw channels capabilities
+openclaw channels capabilities --channel discord --target channel:123
+openclaw channels resolve --channel slack "#general" "@jane"
+openclaw channels logs --channel all
+```
+
+## Add / remove accounts
+
+```bash
+openclaw channels add --channel telegram --token <bot-token>
+openclaw channels remove --channel telegram --delete
+```
+
+Tip: `openclaw channels add --help` shows per-channel flags (token, app token, signal-cli paths, etc).
+
+## Login / logout (interactive)
+
+```bash
+openclaw channels login --channel whatsapp
+openclaw channels logout --channel whatsapp
+```
+
+## Troubleshooting
+
+- Run `openclaw status --deep` for a broad probe.
+- Use `openclaw doctor` for guided fixes.
+- `openclaw channels list` prints `Claude: HTTP 403 ... user:profile` → usage snapshot needs the `user:profile` scope. Use `--no-usage`, or provide a claude.ai session key (`CLAUDE_WEB_SESSION_KEY` / `CLAUDE_WEB_COOKIE`), or re-auth via Claude Code CLI.
+
+## Capabilities probe
+
+Fetch provider capability hints (intents/scopes where available) plus static feature support:
+
+```bash
+openclaw channels capabilities
+openclaw channels capabilities --channel discord --target channel:123
+```
+
+Notes:
+
+- `--channel` is optional; omit it to list every channel (including extensions).
+- `--target` accepts `channel:<id>` or a raw numeric channel id and only applies to Discord.
+- Probes are provider-specific: Discord intents + optional channel permissions; Slack bot + user scopes; Telegram bot flags + webhook; Signal daemon version; MS Teams app token + Graph roles/scopes (annotated where known). Channels without probes report `Probe: unavailable`.
+
+## Resolve names to IDs
+
+Resolve channel/user names to IDs using the provider directory:
+
+```bash
+openclaw channels resolve --channel slack "#general" "@jane"
+openclaw channels resolve --channel discord "My Server/#support" "@someone"
+openclaw channels resolve --channel matrix "Project Room"
+```
+
+Notes:
+
+- Use `--kind user|group|auto` to force the target type.
+- Resolution prefers active matches when multiple entries share the same name.

package/docs/cli/config.md

@@ -0,0 +1,50 @@
+---
+summary: "CLI reference for `openclaw config` (get/set/unset config values)"
+read_when:
+  - You want to read or edit config non-interactively
+title: "config"
+---
+
+# `openclaw config`
+
+Config helpers: get/set/unset values by path. Run without a subcommand to open
+the configure wizard (same as `openclaw configure`).
+
+## Examples
+
+```bash
+openclaw config get browser.executablePath
+openclaw config set browser.executablePath "/usr/bin/google-chrome"
+openclaw config set agents.defaults.heartbeat.every "2h"
+openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
+openclaw config unset tools.web.search.apiKey
+```
+
+## Paths
+
+Paths use dot or bracket notation:
+
+```bash
+openclaw config get agents.defaults.workspace
+openclaw config get agents.list[0].id
+```
+
+Use the agent list index to target a specific agent:
+
+```bash
+openclaw config get agents.list
+openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
+```
+
+## Values
+
+Values are parsed as JSON5 when possible; otherwise they are treated as strings.
+Use `--json` to require JSON5 parsing.
+
+```bash
+openclaw config set agents.defaults.heartbeat.every "0m"
+openclaw config set gateway.port 19001 --json
+openclaw config set channels.whatsapp.groups '["*"]' --json
+```
+
+Restart the gateway after edits.