mirror of
https://github.com/hansjone/oclaw.git
synced 2026-10-09 17:50:47 +08:00
重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。 Made-with: Cursor
This commit is contained in:
parent
4a23b715a2
commit
dbbe3add6a
14438 changed files with 2693620 additions and 2546 deletions
316
openclaw/docs/cli/acp.md
Normal file
316
openclaw/docs/cli/acp.md
Normal file
|
|
@ -0,0 +1,316 @@
|
|||
---
|
||||
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 [Agent Client Protocol (ACP)](https://agentclientprotocol.com/) bridge that talks to an 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.
|
||||
|
||||
`openclaw acp` is a Gateway-backed ACP bridge, not a full ACP-native editor
|
||||
runtime. It focuses on session routing, prompt delivery, and basic streaming
|
||||
updates.
|
||||
|
||||
If you want an external MCP client to talk directly to OpenClaw channel
|
||||
conversations instead of hosting an ACP harness session, use
|
||||
[`openclaw mcp serve`](/cli/mcp) instead.
|
||||
|
||||
## What this is not
|
||||
|
||||
This page is often confused with ACP harness sessions.
|
||||
|
||||
`openclaw acp` means:
|
||||
|
||||
- OpenClaw acts as an ACP server
|
||||
- an IDE or ACP client connects to OpenClaw
|
||||
- OpenClaw forwards that work into a Gateway session
|
||||
|
||||
This is different from [ACP Agents](/tools/acp-agents), where OpenClaw runs an
|
||||
external harness such as Codex or Claude Code through `acpx`.
|
||||
|
||||
Quick rule:
|
||||
|
||||
- editor/client wants to talk ACP to OpenClaw: use `openclaw acp`
|
||||
- OpenClaw should launch Codex/Claude/Gemini as an ACP harness: use `/acp spawn` and [ACP Agents](/tools/acp-agents)
|
||||
|
||||
## Compatibility Matrix
|
||||
|
||||
| ACP area | Status | Notes |
|
||||
| --------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `initialize`, `newSession`, `prompt`, `cancel` | Implemented | Core bridge flow over stdio to Gateway chat/send + abort. |
|
||||
| `listSessions`, slash commands | Implemented | Session list works against Gateway session state; commands are advertised via `available_commands_update`. |
|
||||
| `loadSession` | Partial | Rebinds the ACP session to a Gateway session key and replays stored user/assistant text history. Tool/system history is not reconstructed yet. |
|
||||
| Prompt content (`text`, embedded `resource`, images) | Partial | Text/resources are flattened into chat input; images become Gateway attachments. |
|
||||
| Session modes | Partial | `session/set_mode` is supported and the bridge exposes initial Gateway-backed session controls for thought level, tool verbosity, reasoning, usage detail, and elevated actions. Broader ACP-native mode/config surfaces are still out of scope. |
|
||||
| Session info and usage updates | Partial | The bridge emits `session_info_update` and best-effort `usage_update` notifications from cached Gateway session snapshots. Usage is approximate and only sent when Gateway token totals are marked fresh. |
|
||||
| Tool streaming | Partial | `tool_call` / `tool_call_update` events include raw I/O, text content, and best-effort file locations when Gateway tool args/results expose them. Embedded terminals and richer diff-native output are still not exposed. |
|
||||
| Per-session MCP servers (`mcpServers`) | Unsupported | Bridge mode rejects per-session MCP server requests. Configure MCP on the OpenClaw gateway or agent instead. |
|
||||
| Client filesystem methods (`fs/read_text_file`, `fs/write_text_file`) | Unsupported | The bridge does not call ACP client filesystem methods. |
|
||||
| Client terminal methods (`terminal/*`) | Unsupported | The bridge does not create ACP client terminals or stream terminal ids through tool calls. |
|
||||
| Session plans / thought streaming | Unsupported | The bridge currently emits output text and tool status, not ACP plan or thought updates. |
|
||||
|
||||
## Known Limitations
|
||||
|
||||
- `loadSession` replays stored user and assistant text history, but it does not
|
||||
reconstruct historic tool calls, system notices, or richer ACP-native event
|
||||
types.
|
||||
- If multiple ACP clients share the same Gateway session key, event and cancel
|
||||
routing are best-effort rather than strictly isolated per client. Prefer the
|
||||
default isolated `acp:<uuid>` sessions when you need clean editor-local
|
||||
turns.
|
||||
- Gateway stop states are translated into ACP stop reasons, but that mapping is
|
||||
less expressive than a fully ACP-native runtime.
|
||||
- Initial session controls currently surface a focused subset of Gateway knobs:
|
||||
thought level, tool verbosity, reasoning, usage detail, and elevated
|
||||
actions. Model selection and exec-host controls are not yet exposed as ACP
|
||||
config options.
|
||||
- `session_info_update` and `usage_update` are derived from Gateway session
|
||||
snapshots, not live ACP-native runtime accounting. Usage is approximate,
|
||||
carries no cost data, and is only emitted when the Gateway marks total token
|
||||
data as fresh.
|
||||
- Tool follow-along data is best-effort. The bridge can surface file paths that
|
||||
appear in known tool args/results, but it does not yet emit ACP terminals or
|
||||
structured file diffs.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw acp
|
||||
|
||||
# Remote Gateway
|
||||
openclaw acp --url wss://gateway-host:18789 --token <token>
|
||||
|
||||
# Remote Gateway (token from file)
|
||||
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.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-file ~/.openclaw/gateway.token
|
||||
|
||||
# Override the server command (default: openclaw)
|
||||
openclaw acp client --server "node" --server-args openclaw.mjs acp --url ws://127.0.0.1:19001
|
||||
```
|
||||
|
||||
Permission model (client debug mode):
|
||||
|
||||
- Auto-approval is allowlist-based and only applies to trusted core tool IDs.
|
||||
- `read` auto-approval is scoped to the current working directory (`--cwd` when set).
|
||||
- ACP only auto-approves narrow readonly classes: scoped `read` calls under the active cwd plus readonly search tools (`search`, `web_search`, `memory_search`). Unknown/non-core tools, out-of-scope reads, exec-capable tools, control-plane tools, mutating tools, and interactive flows always require explicit prompt approval.
|
||||
- Server-provided `toolCall.kind` is treated as untrusted metadata (not an authorization source).
|
||||
- This ACP bridge policy is separate from ACPX harness permissions. If you run OpenClaw through the `acpx` backend, `plugins.entries.acpx.config.permissionMode=approve-all` is the break-glass “yolo” switch for that harness session.
|
||||
|
||||
## How to use this
|
||||
|
||||
Use ACP when an IDE (or other client) speaks Agent Client Protocol and you want
|
||||
it to drive an 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>
|
||||
# preferred for local process safety
|
||||
openclaw acp --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.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.
|
||||
|
||||
Per-session `mcpServers` are not supported in bridge mode. If an ACP client
|
||||
sends them during `newSession` or `loadSession`, the bridge returns a clear
|
||||
error instead of silently ignoring them.
|
||||
|
||||
If you want ACPX-backed sessions to see OpenClaw plugin tools, enable the
|
||||
gateway-side ACPX plugin bridge instead of trying to pass per-session
|
||||
`mcpServers`. See [ACP Agents](/tools/acp-agents#plugin-tools-mcp-bridge).
|
||||
|
||||
## Use from `acpx` (Codex, Claude, other ACP clients)
|
||||
|
||||
If you want a coding agent such as Codex or Claude Code to talk to your
|
||||
OpenClaw bot over ACP, use `acpx` with its built-in `openclaw` target.
|
||||
|
||||
Typical flow:
|
||||
|
||||
1. Run the Gateway and make sure the ACP bridge can reach it.
|
||||
2. Point `acpx openclaw` at `openclaw acp`.
|
||||
3. Target the OpenClaw session key you want the coding agent to use.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# One-shot request into your default OpenClaw ACP session
|
||||
acpx openclaw exec "Summarize the active OpenClaw session state."
|
||||
|
||||
# Persistent named session for follow-up turns
|
||||
acpx openclaw sessions ensure --name codex-bridge
|
||||
acpx openclaw -s codex-bridge --cwd /path/to/repo \
|
||||
"Ask my OpenClaw work agent for recent context relevant to this repo."
|
||||
```
|
||||
|
||||
If you want `acpx openclaw` to target a specific Gateway and session key every
|
||||
time, override the `openclaw` agent command in `~/.acpx/config.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"openclaw": {
|
||||
"command": "env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 openclaw acp --url ws://127.0.0.1:18789 --token-file ~/.openclaw/gateway.token --session agent:main:main"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For a repo-local OpenClaw checkout, use the direct CLI entrypoint instead of the
|
||||
dev runner so the ACP stream stays clean. For example:
|
||||
|
||||
```bash
|
||||
env OPENCLAW_HIDE_BANNER=1 OPENCLAW_SUPPRESS_NOTES=1 node openclaw.mjs acp ...
|
||||
```
|
||||
|
||||
This is the easiest way to let Codex, Claude Code, or another ACP-aware client
|
||||
pull contextual information from an OpenClaw agent without scraping a terminal.
|
||||
|
||||
## 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.
|
||||
- `--token-file <path>`: read Gateway auth token from file.
|
||||
- `--password <password>`: Gateway auth password.
|
||||
- `--password-file <path>`: read Gateway auth password from file.
|
||||
- `--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.
|
||||
- `--provenance <off|meta|meta+receipt>`: include ACP provenance metadata or receipts.
|
||||
- `--verbose, -v`: verbose logging to stderr.
|
||||
|
||||
Security note:
|
||||
|
||||
- `--token` and `--password` can be visible in local process listings on some systems.
|
||||
- Prefer `--token-file`/`--password-file` or environment variables (`OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`).
|
||||
- Gateway auth resolution follows the shared contract used by other Gateway clients:
|
||||
- local mode: env (`OPENCLAW_GATEWAY_*`) -> `gateway.auth.*` -> `gateway.remote.*` fallback only when `gateway.auth.*` is unset (configured-but-unresolved local SecretRefs fail closed)
|
||||
- remote mode: `gateway.remote.*` with env/config fallback per remote precedence rules
|
||||
- `--url` is override-safe and does not reuse implicit config/env credentials; pass explicit `--token`/`--password` (or file variants)
|
||||
- ACP runtime backend child processes receive `OPENCLAW_SHELL=acp`, which can be used for context-specific shell/profile rules.
|
||||
- `openclaw acp client` sets `OPENCLAW_SHELL=acp-client` on the spawned bridge process.
|
||||
|
||||
### `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.
|
||||
57
openclaw/docs/cli/agent.md
Normal file
57
openclaw/docs/cli/agent.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
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.
|
||||
|
||||
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 (after plugin registry preload)
|
||||
- `--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.
|
||||
- `--local` still preloads the plugin registry first, so plugin-provided providers, tools, and channels stay available during embedded runs.
|
||||
- `--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.
|
||||
220
openclaw/docs/cli/agents.md
Normal file
220
openclaw/docs/cli/agents.md
Normal file
|
|
@ -0,0 +1,220 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw agents` (list/add/delete/bindings/bind/unbind/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)
|
||||
- Skill visibility config: [Skills config](/tools/skills-config)
|
||||
|
||||
## Examples
|
||||
|
||||
```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
|
||||
openclaw agents set-identity --workspace ~/.openclaw/workspace --from-identity
|
||||
openclaw agents set-identity --agent main --avatar avatars/openclaw.png
|
||||
openclaw agents delete work
|
||||
```
|
||||
|
||||
## Routing bindings
|
||||
|
||||
Use routing bindings to pin inbound channel traffic to a specific agent.
|
||||
|
||||
If you also want different visible skills per agent, configure
|
||||
`agents.defaults.skills` and `agents.list[].skills` in `openclaw.json`. See
|
||||
[Skills config](/tools/skills-config) and
|
||||
[Configuration Reference](/gateway/configuration-reference#agents-defaults-skills).
|
||||
|
||||
List bindings:
|
||||
|
||||
```bash
|
||||
openclaw agents bindings
|
||||
openclaw agents bindings --agent work
|
||||
openclaw agents bindings --json
|
||||
```
|
||||
|
||||
Add bindings:
|
||||
|
||||
```bash
|
||||
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.
|
||||
- `accountId: "*"` is the channel-wide fallback (all accounts) and is less specific than an explicit account binding.
|
||||
- If the same agent already has a matching channel binding without `accountId`, and you later bind with an explicit or resolved `accountId`, OpenClaw upgrades that existing binding in place instead of adding a duplicate.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
# initial channel-only binding
|
||||
openclaw agents bind --agent work --bind telegram
|
||||
|
||||
# later upgrade to account-scoped binding
|
||||
openclaw agents bind --agent work --bind telegram:ops
|
||||
```
|
||||
|
||||
After the upgrade, routing for that binding is scoped to `telegram:ops`. If you also want default-account routing, add it explicitly (for example `--bind telegram:default`).
|
||||
|
||||
Remove bindings:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
- 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)
|
||||
|
||||
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
|
||||
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",
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
185
openclaw/docs/cli/approvals.md
Normal file
185
openclaw/docs/cli/approvals.md
Normal file
|
|
@ -0,0 +1,185 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw approvals` and `openclaw exec-policy`"
|
||||
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.
|
||||
|
||||
Alias: `openclaw exec-approvals`
|
||||
|
||||
Related:
|
||||
|
||||
- Exec approvals: [Exec approvals](/tools/exec-approvals)
|
||||
- Nodes: [Nodes](/nodes)
|
||||
|
||||
## `openclaw exec-policy`
|
||||
|
||||
`openclaw exec-policy` is the local convenience command for keeping the requested
|
||||
`tools.exec.*` config and the local host approvals file aligned in one step.
|
||||
|
||||
Use it when you want to:
|
||||
|
||||
- inspect the local requested policy, host approvals file, and effective merge
|
||||
- apply a local preset such as YOLO or deny-all
|
||||
- synchronize local `tools.exec.*` and local `~/.openclaw/exec-approvals.json`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw exec-policy show
|
||||
openclaw exec-policy show --json
|
||||
|
||||
openclaw exec-policy preset yolo
|
||||
openclaw exec-policy preset cautious --json
|
||||
|
||||
openclaw exec-policy set --host gateway --security full --ask off --ask-fallback full
|
||||
```
|
||||
|
||||
Output modes:
|
||||
|
||||
- no `--json`: prints the human-readable table view
|
||||
- `--json`: prints machine-readable structured output
|
||||
|
||||
Current scope:
|
||||
|
||||
- `exec-policy` is **local-only**
|
||||
- it updates the local config file and the local approvals file together
|
||||
- it does **not** push policy to the gateway host or a node host
|
||||
- `--host node` is rejected in this command because node exec approvals are fetched from the node at runtime and must be managed through node-targeted approvals commands instead
|
||||
- `openclaw exec-policy show` marks `host=node` scopes as node-managed at runtime instead of deriving an effective policy from the local approvals file
|
||||
|
||||
If you need to edit remote host approvals directly, keep using `openclaw approvals set --gateway`
|
||||
or `openclaw approvals set --node <id|name|ip>`.
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw approvals get
|
||||
openclaw approvals get --node <id|name|ip>
|
||||
openclaw approvals get --gateway
|
||||
```
|
||||
|
||||
`openclaw approvals get` now shows the effective exec policy for local, gateway, and node targets:
|
||||
|
||||
- requested `tools.exec` policy
|
||||
- host approvals-file policy
|
||||
- effective result after precedence rules are applied
|
||||
|
||||
Precedence is intentional:
|
||||
|
||||
- the host approvals file is the enforceable source of truth
|
||||
- requested `tools.exec` policy can narrow or broaden intent, but the effective result is still derived from the host rules
|
||||
- `--node` combines the node host approvals file with gateway `tools.exec` policy, because both still apply at runtime
|
||||
- if gateway config is unavailable, the CLI falls back to the node approvals snapshot and notes that the final runtime policy could not be computed
|
||||
|
||||
## Replace approvals from a file
|
||||
|
||||
```bash
|
||||
openclaw approvals set --file ./exec-approvals.json
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
{ version: 1, defaults: { security: "full", ask: "off" } }
|
||||
EOF
|
||||
openclaw approvals set --node <id|name|ip> --file ./exec-approvals.json
|
||||
openclaw approvals set --gateway --file ./exec-approvals.json
|
||||
```
|
||||
|
||||
`set` accepts JSON5, not only strict JSON. Use either `--file` or `--stdin`, not both.
|
||||
|
||||
## "Never prompt" / YOLO example
|
||||
|
||||
For a host that should never stop on exec approvals, set the host approvals defaults to `full` + `off`:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --stdin <<'EOF'
|
||||
{
|
||||
version: 1,
|
||||
defaults: {
|
||||
security: "full",
|
||||
ask: "off",
|
||||
askFallback: "full"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
Node variant:
|
||||
|
||||
```bash
|
||||
openclaw approvals set --node <id|name|ip> --stdin <<'EOF'
|
||||
{
|
||||
version: 1,
|
||||
defaults: {
|
||||
security: "full",
|
||||
ask: "off",
|
||||
askFallback: "full"
|
||||
}
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
This changes the **host approvals file** only. To keep the requested OpenClaw policy aligned, also set:
|
||||
|
||||
```bash
|
||||
openclaw config set tools.exec.host gateway
|
||||
openclaw config set tools.exec.security full
|
||||
openclaw config set tools.exec.ask off
|
||||
```
|
||||
|
||||
Why `tools.exec.host=gateway` in this example:
|
||||
|
||||
- `host=auto` still means "sandbox when available, otherwise gateway".
|
||||
- YOLO is about approvals, not routing.
|
||||
- If you want host exec even when a sandbox is configured, make the host choice explicit with `gateway` or `/exec host=gateway`.
|
||||
|
||||
This matches the current host-default YOLO behavior. Tighten it if you want approvals.
|
||||
|
||||
Local shortcut:
|
||||
|
||||
```bash
|
||||
openclaw exec-policy preset yolo
|
||||
```
|
||||
|
||||
That local shortcut updates both the requested local `tools.exec.*` config and the
|
||||
local approvals defaults together. It is equivalent in intent to the manual two-step
|
||||
setup above, but only for the local machine.
|
||||
|
||||
## 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"
|
||||
```
|
||||
|
||||
## Common options
|
||||
|
||||
`get`, `set`, and `allowlist add|remove` all support:
|
||||
|
||||
- `--node <id|name|ip>`
|
||||
- `--gateway`
|
||||
- shared node RPC options: `--url`, `--token`, `--timeout`, `--json`
|
||||
|
||||
Targeting notes:
|
||||
|
||||
- no target flags means the local approvals file on disk
|
||||
- `--gateway` targets the gateway host approvals file
|
||||
- `--node` targets one node host after resolving id, name, IP, or id prefix
|
||||
|
||||
`allowlist add|remove` also supports:
|
||||
|
||||
- `--agent <id>` (defaults to `*`)
|
||||
|
||||
## 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`.
|
||||
84
openclaw/docs/cli/backup.md
Normal file
84
openclaw/docs/cli/backup.md
Normal file
|
|
@ -0,0 +1,84 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw backup` (create local backup archives)"
|
||||
read_when:
|
||||
- You want a first-class backup archive for local OpenClaw state
|
||||
- You want to preview which paths would be included before reset or uninstall
|
||||
title: "backup"
|
||||
---
|
||||
|
||||
# `openclaw backup`
|
||||
|
||||
Create a local backup archive for OpenClaw state, config, auth profiles, channel/provider credentials, sessions, and optionally workspaces.
|
||||
|
||||
```bash
|
||||
openclaw backup create
|
||||
openclaw backup create --output ~/Backups
|
||||
openclaw backup create --dry-run --json
|
||||
openclaw backup create --verify
|
||||
openclaw backup create --no-include-workspace
|
||||
openclaw backup create --only-config
|
||||
openclaw backup verify ./2026-03-09T00-00-00.000Z-openclaw-backup.tar.gz
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- The archive includes a `manifest.json` file with the resolved source paths and archive layout.
|
||||
- Default output is a timestamped `.tar.gz` archive in the current working directory.
|
||||
- If the current working directory is inside a backed-up source tree, OpenClaw falls back to your home directory for the default archive location.
|
||||
- Existing archive files are never overwritten.
|
||||
- Output paths inside the source state/workspace trees are rejected to avoid self-inclusion.
|
||||
- `openclaw backup verify <archive>` validates that the archive contains exactly one root manifest, rejects traversal-style archive paths, and checks that every manifest-declared payload exists in the tarball.
|
||||
- `openclaw backup create --verify` runs that validation immediately after writing the archive.
|
||||
- `openclaw backup create --only-config` backs up just the active JSON config file.
|
||||
|
||||
## What gets backed up
|
||||
|
||||
`openclaw backup create` plans backup sources from your local OpenClaw install:
|
||||
|
||||
- The state directory returned by OpenClaw's local state resolver, usually `~/.openclaw`
|
||||
- The active config file path
|
||||
- The resolved `credentials/` directory when it exists outside the state directory
|
||||
- Workspace directories discovered from the current config, unless you pass `--no-include-workspace`
|
||||
|
||||
Model auth profiles are already part of the state directory under
|
||||
`agents/<agentId>/agent/auth-profiles.json`, so they are normally covered by the
|
||||
state backup entry.
|
||||
|
||||
If you use `--only-config`, OpenClaw skips state, credentials-directory, and workspace discovery and archives only the active config file path.
|
||||
|
||||
OpenClaw canonicalizes paths before building the archive. If config, the
|
||||
credentials directory, or a workspace already live inside the state directory,
|
||||
they are not duplicated as separate top-level backup sources. Missing paths are
|
||||
skipped.
|
||||
|
||||
The archive payload stores file contents from those source trees, and the embedded `manifest.json` records the resolved absolute source paths plus the archive layout used for each asset.
|
||||
|
||||
## Invalid config behavior
|
||||
|
||||
`openclaw backup` intentionally bypasses the normal config preflight so it can still help during recovery. Because workspace discovery depends on a valid config, `openclaw backup create` now fails fast when the config file exists but is invalid and workspace backup is still enabled.
|
||||
|
||||
If you still want a partial backup in that situation, rerun:
|
||||
|
||||
```bash
|
||||
openclaw backup create --no-include-workspace
|
||||
```
|
||||
|
||||
That keeps state, config, and the external credentials directory in scope while
|
||||
skipping workspace discovery entirely.
|
||||
|
||||
If you only need a copy of the config file itself, `--only-config` also works when the config is malformed because it does not rely on parsing the config for workspace discovery.
|
||||
|
||||
## Size and performance
|
||||
|
||||
OpenClaw does not enforce a built-in maximum backup size or per-file size limit.
|
||||
|
||||
Practical limits come from the local machine and destination filesystem:
|
||||
|
||||
- Available space for the temporary archive write plus the final archive
|
||||
- Time to walk large workspace trees and compress them into a `.tar.gz`
|
||||
- Time to rescan the archive if you use `openclaw backup create --verify` or run `openclaw backup verify`
|
||||
- Filesystem behavior at the destination path. OpenClaw prefers a no-overwrite hard-link publish step and falls back to exclusive copy when hard links are unsupported
|
||||
|
||||
Large workspaces are usually the main driver of archive size. If you want a smaller or faster backup, use `--no-include-workspace`.
|
||||
|
||||
For the smallest archive, use `--only-config`.
|
||||
247
openclaw/docs/cli/browser.md
Normal file
247
openclaw/docs/cli/browser.md
Normal file
|
|
@ -0,0 +1,247 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw browser` (lifecycle, profiles, tabs, actions, state, and debugging)"
|
||||
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 attach to your local signed-in Chrome via Chrome MCP
|
||||
title: "browser"
|
||||
---
|
||||
|
||||
# `openclaw browser`
|
||||
|
||||
Manage OpenClaw's browser control surface and run browser actions (lifecycle, profiles, tabs, snapshots, screenshots, navigation, input, state emulation, and debugging).
|
||||
|
||||
Related:
|
||||
|
||||
- Browser tool + API: [Browser tool](/tools/browser)
|
||||
|
||||
## Common flags
|
||||
|
||||
- `--url <gatewayWsUrl>`: Gateway WebSocket URL (defaults to config).
|
||||
- `--token <token>`: Gateway token (if required).
|
||||
- `--timeout <ms>`: request timeout (ms).
|
||||
- `--expect-final`: wait for a final Gateway response.
|
||||
- `--browser-profile <name>`: choose a browser profile (default from config).
|
||||
- `--json`: machine-readable output (where supported).
|
||||
|
||||
## Quick start (local)
|
||||
|
||||
```bash
|
||||
openclaw browser profiles
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
openclaw browser --browser-profile openclaw snapshot
|
||||
```
|
||||
|
||||
## Quick troubleshooting
|
||||
|
||||
If `start` fails with `not reachable after start`, troubleshoot CDP readiness first. If `start` and `tabs` succeed but `open` or `navigate` fails, the browser control plane is healthy and the failure is usually navigation SSRF policy.
|
||||
|
||||
Minimal sequence:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile openclaw start
|
||||
openclaw browser --browser-profile openclaw tabs
|
||||
openclaw browser --browser-profile openclaw open https://example.com
|
||||
```
|
||||
|
||||
Detailed guidance: [Browser troubleshooting](/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block)
|
||||
|
||||
## Lifecycle
|
||||
|
||||
```bash
|
||||
openclaw browser status
|
||||
openclaw browser start
|
||||
openclaw browser stop
|
||||
openclaw browser --browser-profile openclaw reset-profile
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- For `attachOnly` and remote CDP profiles, `openclaw browser stop` closes the
|
||||
active control session and clears temporary emulation overrides even when
|
||||
OpenClaw did not launch the browser process itself.
|
||||
- For local managed profiles, `openclaw browser stop` stops the spawned browser
|
||||
process.
|
||||
|
||||
## If the command is missing
|
||||
|
||||
If `openclaw browser` is an unknown command, check `plugins.allow` in
|
||||
`~/.openclaw/openclaw.json`.
|
||||
|
||||
When `plugins.allow` is present, the bundled browser plugin must be listed
|
||||
explicitly:
|
||||
|
||||
```json5
|
||||
{
|
||||
plugins: {
|
||||
allow: ["telegram", "browser"],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`browser.enabled=true` does not restore the CLI subcommand when the plugin
|
||||
allowlist excludes `browser`.
|
||||
|
||||
Related: [Browser tool](/tools/browser#missing-browser-command-or-tool)
|
||||
|
||||
## Profiles
|
||||
|
||||
Profiles are named browser routing configs. In practice:
|
||||
|
||||
- `openclaw`: launches or attaches to a dedicated OpenClaw-managed Chrome instance (isolated user data dir).
|
||||
- `user`: controls your existing signed-in Chrome session via Chrome DevTools MCP.
|
||||
- custom CDP profiles: point at a local or remote CDP endpoint.
|
||||
|
||||
```bash
|
||||
openclaw browser profiles
|
||||
openclaw browser create-profile --name work --color "#FF5A36"
|
||||
openclaw browser create-profile --name chrome-live --driver existing-session
|
||||
openclaw browser create-profile --name remote --cdp-url https://browser-host.example.com
|
||||
openclaw browser delete-profile --name work
|
||||
```
|
||||
|
||||
Use a specific profile:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile work tabs
|
||||
```
|
||||
|
||||
## Tabs
|
||||
|
||||
```bash
|
||||
openclaw browser tabs
|
||||
openclaw browser tab new
|
||||
openclaw browser tab select 2
|
||||
openclaw browser tab close 2
|
||||
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
|
||||
openclaw browser screenshot --full-page
|
||||
openclaw browser screenshot --ref e12
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `--full-page` is for page captures only; it cannot be combined with `--ref`
|
||||
or `--element`.
|
||||
- `existing-session` / `user` profiles support page screenshots and `--ref`
|
||||
screenshots from snapshot output, but not CSS `--element` screenshots.
|
||||
|
||||
Navigate/click/type (ref-based UI automation):
|
||||
|
||||
```bash
|
||||
openclaw browser navigate https://example.com
|
||||
openclaw browser click <ref>
|
||||
openclaw browser type <ref> "hello"
|
||||
openclaw browser press Enter
|
||||
openclaw browser hover <ref>
|
||||
openclaw browser scrollintoview <ref>
|
||||
openclaw browser drag <startRef> <endRef>
|
||||
openclaw browser select <ref> OptionA OptionB
|
||||
openclaw browser fill --fields '[{"ref":"1","value":"Ada"}]'
|
||||
openclaw browser wait --text "Done"
|
||||
openclaw browser evaluate --fn '(el) => el.textContent' --ref <ref>
|
||||
```
|
||||
|
||||
File + dialog helpers:
|
||||
|
||||
```bash
|
||||
openclaw browser upload /tmp/openclaw/uploads/file.pdf --ref <ref>
|
||||
openclaw browser waitfordownload
|
||||
openclaw browser download <ref> report.pdf
|
||||
openclaw browser dialog --accept
|
||||
```
|
||||
|
||||
## State and storage
|
||||
|
||||
Viewport + emulation:
|
||||
|
||||
```bash
|
||||
openclaw browser resize 1280 720
|
||||
openclaw browser set viewport 1280 720
|
||||
openclaw browser set offline on
|
||||
openclaw browser set media dark
|
||||
openclaw browser set timezone Europe/London
|
||||
openclaw browser set locale en-GB
|
||||
openclaw browser set geo 51.5074 -0.1278 --accuracy 25
|
||||
openclaw browser set device "iPhone 14"
|
||||
openclaw browser set headers '{"x-test":"1"}'
|
||||
openclaw browser set credentials myuser mypass
|
||||
```
|
||||
|
||||
Cookies + storage:
|
||||
|
||||
```bash
|
||||
openclaw browser cookies
|
||||
openclaw browser cookies set session abc123 --url https://example.com
|
||||
openclaw browser cookies clear
|
||||
openclaw browser storage local get
|
||||
openclaw browser storage local set token abc123
|
||||
openclaw browser storage session clear
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
```bash
|
||||
openclaw browser console --level error
|
||||
openclaw browser pdf
|
||||
openclaw browser responsebody "**/api"
|
||||
openclaw browser highlight <ref>
|
||||
openclaw browser errors --clear
|
||||
openclaw browser requests --filter api
|
||||
openclaw browser trace start
|
||||
openclaw browser trace stop --out trace.zip
|
||||
```
|
||||
|
||||
## Existing Chrome via MCP
|
||||
|
||||
Use the built-in `user` profile, or create your own `existing-session` profile:
|
||||
|
||||
```bash
|
||||
openclaw browser --browser-profile user tabs
|
||||
openclaw browser create-profile --name chrome-live --driver existing-session
|
||||
openclaw browser create-profile --name brave-live --driver existing-session --user-data-dir "~/Library/Application Support/BraveSoftware/Brave-Browser"
|
||||
openclaw browser --browser-profile chrome-live tabs
|
||||
```
|
||||
|
||||
This path is host-only. For Docker, headless servers, Browserless, or other remote setups, use a CDP profile instead.
|
||||
|
||||
Current existing-session limits:
|
||||
|
||||
- snapshot-driven actions use refs, not CSS selectors
|
||||
- `click` is left-click only
|
||||
- `type` does not support `slowly=true`
|
||||
- `press` does not support `delayMs`
|
||||
- `hover`, `scrollintoview`, `drag`, `select`, `fill`, and `evaluate` reject
|
||||
per-call timeout overrides
|
||||
- `select` supports one value only
|
||||
- `wait --load networkidle` is not supported
|
||||
- file uploads require `--ref` / `--input-ref`, do not support CSS
|
||||
`--element`, and currently support one file at a time
|
||||
- dialog hooks do not support `--timeout`
|
||||
- screenshots support page captures and `--ref`, but not CSS `--element`
|
||||
- `responsebody`, download interception, PDF export, and batch actions still
|
||||
require a managed browser or raw CDP profile
|
||||
|
||||
## 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)
|
||||
131
openclaw/docs/cli/channels.md
Normal file
131
openclaw/docs/cli/channels.md
Normal file
|
|
@ -0,0 +1,131 @@
|
|||
---
|
||||
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/Matrix)
|
||||
- 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
|
||||
```
|
||||
|
||||
## Status / capabilities / resolve / logs
|
||||
|
||||
- `channels status`: `--probe`, `--timeout <ms>`, `--json`
|
||||
- `channels capabilities`: `--channel <name>`, `--account <id>` (only with `--channel`), `--target <dest>`, `--timeout <ms>`, `--json`
|
||||
- `channels resolve`: `<entries...>`, `--channel <name>`, `--account <id>`, `--kind <auto|user|group>`, `--json`
|
||||
- `channels logs`: `--channel <name|all>`, `--lines <n>`, `--json`
|
||||
|
||||
`channels status --probe` is the live path: on a reachable gateway it runs per-account
|
||||
`probeAccount` and optional `auditAccount` checks, so output can include transport
|
||||
state plus probe results such as `works`, `probe failed`, `audit ok`, or `audit failed`.
|
||||
If the gateway is unreachable, `channels status` falls back to config-only summaries
|
||||
instead of live probe output.
|
||||
|
||||
## Add / remove accounts
|
||||
|
||||
```bash
|
||||
openclaw channels add --channel telegram --token <bot-token>
|
||||
openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY"
|
||||
openclaw channels remove --channel telegram --delete
|
||||
```
|
||||
|
||||
Tip: `openclaw channels add --help` shows per-channel flags (token, private key, app token, signal-cli paths, etc).
|
||||
|
||||
Common non-interactive add surfaces include:
|
||||
|
||||
- bot-token channels: `--token`, `--bot-token`, `--app-token`, `--token-file`
|
||||
- Signal/iMessage transport fields: `--signal-number`, `--cli-path`, `--http-url`, `--http-host`, `--http-port`, `--db-path`, `--service`, `--region`
|
||||
- Google Chat fields: `--webhook-path`, `--webhook-url`, `--audience-type`, `--audience`
|
||||
- Matrix fields: `--homeserver`, `--user-id`, `--access-token`, `--password`, `--device-name`, `--initial-sync-limit`
|
||||
- Nostr fields: `--private-key`, `--relay-urls`
|
||||
- Tlon fields: `--ship`, `--url`, `--code`, `--group-channels`, `--dm-allowlist`, `--auto-discover-channels`
|
||||
- `--use-env` for default-account env-backed auth where supported
|
||||
|
||||
When you run `openclaw channels add` without flags, the interactive wizard can prompt:
|
||||
|
||||
- account ids per selected channel
|
||||
- optional display names for those accounts
|
||||
- `Bind configured channel accounts to agents now?`
|
||||
|
||||
If you confirm bind now, the wizard asks which agent should own each configured channel account and writes account-scoped routing bindings.
|
||||
|
||||
You can also manage the same routing rules later with `openclaw agents bindings`, `openclaw agents bind`, and `openclaw agents unbind` (see [agents](/cli/agents)).
|
||||
|
||||
When you add a non-default account to a channel that is still using single-account top-level settings, OpenClaw promotes account-scoped top-level values into the channel's account map before writing the new account. Most channels land those values in `channels.<channel>.accounts.default`, but bundled channels can preserve an existing matching promoted account instead. Matrix is the current example: if one named account already exists, or `defaultAccount` points at an existing named account, promotion preserves that account instead of creating a new `accounts.default`.
|
||||
|
||||
Routing behavior stays consistent:
|
||||
|
||||
- Existing channel-only bindings (no `accountId`) continue to match the default account.
|
||||
- `channels add` does not auto-create or rewrite bindings in non-interactive mode.
|
||||
- Interactive setup can optionally add account-scoped bindings.
|
||||
|
||||
If your config was already in a mixed state (named accounts present and top-level single-account values still set), run `openclaw doctor --fix` to move account-scoped values into the promoted account chosen for that channel. Most channels promote into `accounts.default`; Matrix can preserve an existing named/default target instead.
|
||||
|
||||
## Login / logout (interactive)
|
||||
|
||||
```bash
|
||||
openclaw channels login --channel whatsapp
|
||||
openclaw channels logout --channel whatsapp
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `channels login` supports `--verbose`.
|
||||
- `channels login` / `logout` can infer the channel when only one supported login target is configured.
|
||||
|
||||
## 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 CLI.
|
||||
- `openclaw channels status` falls back to config-only summaries when the gateway is unreachable. If a supported channel credential is configured via SecretRef but unavailable in the current command path, it reports that account as configured with degraded notes instead of showing it as not configured.
|
||||
|
||||
## 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).
|
||||
- `--account` is only valid with `--channel`.
|
||||
- `--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; Microsoft 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.
|
||||
- `channels resolve` is read-only. If a selected account is configured via SecretRef but that credential is unavailable in the current command path, the command returns degraded unresolved results with notes instead of aborting the entire run.
|
||||
21
openclaw/docs/cli/clawbot.md
Normal file
21
openclaw/docs/cli/clawbot.md
Normal file
|
|
@ -0,0 +1,21 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw clawbot` (legacy alias namespace)"
|
||||
read_when:
|
||||
- You maintain older scripts using `openclaw clawbot ...`
|
||||
- You need migration guidance to current commands
|
||||
title: "clawbot"
|
||||
---
|
||||
|
||||
# `openclaw clawbot`
|
||||
|
||||
Legacy alias namespace kept for backwards compatibility.
|
||||
|
||||
Current supported alias:
|
||||
|
||||
- `openclaw clawbot qr` (same behavior as [`openclaw qr`](/cli/qr))
|
||||
|
||||
## Migration
|
||||
|
||||
Prefer modern top-level commands directly:
|
||||
|
||||
- `openclaw clawbot qr` -> `openclaw qr`
|
||||
35
openclaw/docs/cli/completion.md
Normal file
35
openclaw/docs/cli/completion.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw completion` (generate/install shell completion scripts)"
|
||||
read_when:
|
||||
- You want shell completions for zsh/bash/fish/PowerShell
|
||||
- You need to cache completion scripts under OpenClaw state
|
||||
title: "completion"
|
||||
---
|
||||
|
||||
# `openclaw completion`
|
||||
|
||||
Generate shell completion scripts and optionally install them into your shell profile.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw completion
|
||||
openclaw completion --shell zsh
|
||||
openclaw completion --install
|
||||
openclaw completion --shell fish --install
|
||||
openclaw completion --write-state
|
||||
openclaw completion --shell bash --write-state
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `-s, --shell <shell>`: shell target (`zsh`, `bash`, `powershell`, `fish`; default: `zsh`)
|
||||
- `-i, --install`: install completion by adding a source line to your shell profile
|
||||
- `--write-state`: write completion script(s) to `$OPENCLAW_STATE_DIR/completions` without printing to stdout
|
||||
- `-y, --yes`: skip install confirmation prompts
|
||||
|
||||
## Notes
|
||||
|
||||
- `--install` writes a small "OpenClaw Completion" block into your shell profile and points it at the cached script.
|
||||
- Without `--install` or `--write-state`, the command prints the script to stdout.
|
||||
- Completion generation eagerly loads command trees so nested subcommands are included.
|
||||
381
openclaw/docs/cli/config.md
Normal file
381
openclaw/docs/cli/config.md
Normal file
|
|
@ -0,0 +1,381 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw config` (get/set/unset/file/schema/validate)"
|
||||
read_when:
|
||||
- You want to read or edit config non-interactively
|
||||
title: "config"
|
||||
---
|
||||
|
||||
# `openclaw config`
|
||||
|
||||
Config helpers for non-interactive edits in `openclaw.json`: get/set/unset/file/schema/validate
|
||||
values by path and print the active config file. Run without a subcommand to
|
||||
open the configure wizard (same as `openclaw configure`).
|
||||
|
||||
Root options:
|
||||
|
||||
- `--section <section>`: repeatable guided-setup section filter when you run `openclaw config` without a subcommand
|
||||
|
||||
Supported guided sections:
|
||||
|
||||
- `workspace`
|
||||
- `model`
|
||||
- `web`
|
||||
- `gateway`
|
||||
- `daemon`
|
||||
- `channels`
|
||||
- `plugins`
|
||||
- `skills`
|
||||
- `health`
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw config file
|
||||
openclaw config --section model
|
||||
openclaw config --section gateway --section daemon
|
||||
openclaw config schema
|
||||
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 set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
|
||||
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
|
||||
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
|
||||
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
|
||||
openclaw config validate
|
||||
openclaw config validate --json
|
||||
```
|
||||
|
||||
### `config schema`
|
||||
|
||||
Print the generated JSON schema for `openclaw.json` to stdout as JSON.
|
||||
|
||||
What it includes:
|
||||
|
||||
- The current root config schema, plus a root `$schema` string field for editor tooling
|
||||
- Field `title` and `description` docs metadata used by the Control UI
|
||||
- Nested object, wildcard (`*`), and array-item (`[]`) nodes inherit the same `title` / `description` metadata when matching field documentation exists
|
||||
- `anyOf` / `oneOf` / `allOf` branches inherit the same docs metadata too when matching field documentation exists
|
||||
- Best-effort live plugin + channel schema metadata when runtime manifests can be loaded
|
||||
- A clean fallback schema even when the current config is invalid
|
||||
|
||||
Related runtime RPC:
|
||||
|
||||
- `config.schema.lookup` returns one normalized config path with a shallow
|
||||
schema node (`title`, `description`, `type`, `enum`, `const`, common bounds),
|
||||
matched UI hint metadata, and immediate child summaries. Use it for
|
||||
path-scoped drill-down in Control UI or custom clients.
|
||||
|
||||
```bash
|
||||
openclaw config schema
|
||||
```
|
||||
|
||||
Pipe it into a file when you want to inspect or validate it with other tools:
|
||||
|
||||
```bash
|
||||
openclaw config schema > openclaw.schema.json
|
||||
```
|
||||
|
||||
### 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 `--strict-json` to require JSON5 parsing. `--json` remains supported as a legacy alias.
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.heartbeat.every "0m"
|
||||
openclaw config set gateway.port 19001 --strict-json
|
||||
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
|
||||
```
|
||||
|
||||
`config get <path> --json` prints the raw value as JSON instead of terminal-formatted text.
|
||||
|
||||
## `config set` modes
|
||||
|
||||
`openclaw config set` supports four assignment styles:
|
||||
|
||||
1. Value mode: `openclaw config set <path> <value>`
|
||||
2. SecretRef builder mode:
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider default \
|
||||
--ref-source env \
|
||||
--ref-id DISCORD_BOT_TOKEN
|
||||
```
|
||||
|
||||
3. Provider builder mode (`secrets.providers.<alias>` path only):
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
--provider-source exec \
|
||||
--provider-command /usr/local/bin/openclaw-vault \
|
||||
--provider-arg read \
|
||||
--provider-arg openai/api-key \
|
||||
--provider-timeout-ms 5000
|
||||
```
|
||||
|
||||
4. Batch mode (`--batch-json` or `--batch-file`):
|
||||
|
||||
```bash
|
||||
openclaw config set --batch-json '[
|
||||
{
|
||||
"path": "secrets.providers.default",
|
||||
"provider": { "source": "env" }
|
||||
},
|
||||
{
|
||||
"path": "channels.discord.token",
|
||||
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
|
||||
}
|
||||
]'
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw config set --batch-file ./config-set.batch.json --dry-run
|
||||
```
|
||||
|
||||
Policy note:
|
||||
|
||||
- SecretRef assignments are rejected on unsupported runtime-mutable surfaces (for example `hooks.token`, `commands.ownerDisplaySecret`, Discord thread-binding webhook tokens, and WhatsApp creds JSON). See [SecretRef Credential Surface](/reference/secretref-credential-surface).
|
||||
|
||||
Batch parsing always uses the batch payload (`--batch-json`/`--batch-file`) as the source of truth.
|
||||
`--strict-json` / `--json` do not change batch parsing behavior.
|
||||
|
||||
JSON path/value mode remains supported for both SecretRefs and providers:
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
'{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
|
||||
--strict-json
|
||||
|
||||
openclaw config set secrets.providers.vaultfile \
|
||||
'{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
|
||||
--strict-json
|
||||
```
|
||||
|
||||
## Provider Builder Flags
|
||||
|
||||
Provider builder targets must use `secrets.providers.<alias>` as the path.
|
||||
|
||||
Common flags:
|
||||
|
||||
- `--provider-source <env|file|exec>`
|
||||
- `--provider-timeout-ms <ms>` (`file`, `exec`)
|
||||
|
||||
Env provider (`--provider-source env`):
|
||||
|
||||
- `--provider-allowlist <ENV_VAR>` (repeatable)
|
||||
|
||||
File provider (`--provider-source file`):
|
||||
|
||||
- `--provider-path <path>` (required)
|
||||
- `--provider-mode <singleValue|json>`
|
||||
- `--provider-max-bytes <bytes>`
|
||||
|
||||
Exec provider (`--provider-source exec`):
|
||||
|
||||
- `--provider-command <path>` (required)
|
||||
- `--provider-arg <arg>` (repeatable)
|
||||
- `--provider-no-output-timeout-ms <ms>`
|
||||
- `--provider-max-output-bytes <bytes>`
|
||||
- `--provider-json-only`
|
||||
- `--provider-env <KEY=VALUE>` (repeatable)
|
||||
- `--provider-pass-env <ENV_VAR>` (repeatable)
|
||||
- `--provider-trusted-dir <path>` (repeatable)
|
||||
- `--provider-allow-insecure-path`
|
||||
- `--provider-allow-symlink-command`
|
||||
|
||||
Hardened exec provider example:
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
--provider-source exec \
|
||||
--provider-command /usr/local/bin/openclaw-vault \
|
||||
--provider-arg read \
|
||||
--provider-arg openai/api-key \
|
||||
--provider-json-only \
|
||||
--provider-pass-env VAULT_TOKEN \
|
||||
--provider-trusted-dir /usr/local/bin \
|
||||
--provider-timeout-ms 5000
|
||||
```
|
||||
|
||||
## Dry run
|
||||
|
||||
Use `--dry-run` to validate changes without writing `openclaw.json`.
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider default \
|
||||
--ref-source env \
|
||||
--ref-id DISCORD_BOT_TOKEN \
|
||||
--dry-run
|
||||
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider default \
|
||||
--ref-source env \
|
||||
--ref-id DISCORD_BOT_TOKEN \
|
||||
--dry-run \
|
||||
--json
|
||||
|
||||
openclaw config set channels.discord.token \
|
||||
--ref-provider vault \
|
||||
--ref-source exec \
|
||||
--ref-id discord/token \
|
||||
--dry-run \
|
||||
--allow-exec
|
||||
```
|
||||
|
||||
Dry-run behavior:
|
||||
|
||||
- Builder mode: runs SecretRef resolvability checks for changed refs/providers.
|
||||
- JSON mode (`--strict-json`, `--json`, or batch mode): runs schema validation plus SecretRef resolvability checks.
|
||||
- Policy validation also runs for known unsupported SecretRef target surfaces.
|
||||
- Policy checks evaluate the full post-change config, so parent-object writes (for example setting `hooks` as an object) cannot bypass unsupported-surface validation.
|
||||
- Exec SecretRef checks are skipped by default during dry-run to avoid command side effects.
|
||||
- Use `--allow-exec` with `--dry-run` to opt in to exec SecretRef checks (this may execute provider commands).
|
||||
- `--allow-exec` is dry-run only and errors if used without `--dry-run`.
|
||||
|
||||
`--dry-run --json` prints a machine-readable report:
|
||||
|
||||
- `ok`: whether dry-run passed
|
||||
- `operations`: number of assignments evaluated
|
||||
- `checks`: whether schema/resolvability checks ran
|
||||
- `checks.resolvabilityComplete`: whether resolvability checks ran to completion (false when exec refs are skipped)
|
||||
- `refsChecked`: number of refs actually resolved during dry-run
|
||||
- `skippedExecRefs`: number of exec refs skipped because `--allow-exec` was not set
|
||||
- `errors`: structured schema/resolvability failures when `ok=false`
|
||||
|
||||
### JSON Output Shape
|
||||
|
||||
```json5
|
||||
{
|
||||
ok: boolean,
|
||||
operations: number,
|
||||
configPath: string,
|
||||
inputModes: ["value" | "json" | "builder", ...],
|
||||
checks: {
|
||||
schema: boolean,
|
||||
resolvability: boolean,
|
||||
resolvabilityComplete: boolean,
|
||||
},
|
||||
refsChecked: number,
|
||||
skippedExecRefs: number,
|
||||
errors?: [
|
||||
{
|
||||
kind: "schema" | "resolvability",
|
||||
message: string,
|
||||
ref?: string, // present for resolvability errors
|
||||
},
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
Success example:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"operations": 1,
|
||||
"configPath": "~/.openclaw/openclaw.json",
|
||||
"inputModes": ["builder"],
|
||||
"checks": {
|
||||
"schema": false,
|
||||
"resolvability": true,
|
||||
"resolvabilityComplete": true
|
||||
},
|
||||
"refsChecked": 1,
|
||||
"skippedExecRefs": 0
|
||||
}
|
||||
```
|
||||
|
||||
Failure example:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": false,
|
||||
"operations": 1,
|
||||
"configPath": "~/.openclaw/openclaw.json",
|
||||
"inputModes": ["builder"],
|
||||
"checks": {
|
||||
"schema": false,
|
||||
"resolvability": true,
|
||||
"resolvabilityComplete": true
|
||||
},
|
||||
"refsChecked": 1,
|
||||
"skippedExecRefs": 0,
|
||||
"errors": [
|
||||
{
|
||||
"kind": "resolvability",
|
||||
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
|
||||
"ref": "env:default:MISSING_TEST_SECRET"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If dry-run fails:
|
||||
|
||||
- `config schema validation failed`: your post-change config shape is invalid; fix path/value or provider/ref object shape.
|
||||
- `Config policy validation failed: unsupported SecretRef usage`: move that credential back to plaintext/string input and keep SecretRefs on supported surfaces only.
|
||||
- `SecretRef assignment(s) could not be resolved`: referenced provider/ref currently cannot resolve (missing env var, invalid file pointer, exec provider failure, or provider/source mismatch).
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`: dry-run skipped exec refs; rerun with `--allow-exec` if you need exec resolvability validation.
|
||||
- For batch mode, fix failing entries and rerun `--dry-run` before writing.
|
||||
|
||||
## Write safety
|
||||
|
||||
`openclaw config set` and other OpenClaw-owned config writers validate the full
|
||||
post-change config before committing it to disk. If the new payload fails schema
|
||||
validation or looks like a destructive clobber, the active config is left alone
|
||||
and the rejected payload is saved beside it as `openclaw.json.rejected.*`.
|
||||
|
||||
Prefer CLI writes for small edits:
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.reload.mode hybrid --dry-run
|
||||
openclaw config set gateway.reload.mode hybrid
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
If a write is rejected, inspect the saved payload and fix the full config shape:
|
||||
|
||||
```bash
|
||||
CONFIG="$(openclaw config file)"
|
||||
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
Direct editor writes are still allowed, but the running Gateway treats them as
|
||||
untrusted until they validate. Invalid direct edits can be restored from the
|
||||
last-known-good backup during startup or hot reload. See
|
||||
[Gateway troubleshooting](/gateway/troubleshooting#gateway-restored-last-known-good-config).
|
||||
|
||||
## Subcommands
|
||||
|
||||
- `config file`: Print the active config file path (resolved from `OPENCLAW_CONFIG_PATH` or default location).
|
||||
|
||||
Restart the gateway after edits.
|
||||
|
||||
## Validate
|
||||
|
||||
Validate the current config against the active schema without starting the
|
||||
gateway.
|
||||
|
||||
```bash
|
||||
openclaw config validate
|
||||
openclaw config validate --json
|
||||
```
|
||||
70
openclaw/docs/cli/configure.md
Normal file
70
openclaw/docs/cli/configure.md
Normal file
|
|
@ -0,0 +1,70 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw configure` (interactive configuration prompts)"
|
||||
read_when:
|
||||
- You want to tweak credentials, devices, or agent defaults interactively
|
||||
title: "configure"
|
||||
---
|
||||
|
||||
# `openclaw configure`
|
||||
|
||||
Interactive prompt to set up credentials, devices, and agent defaults.
|
||||
|
||||
Note: The **Model** section now includes a multi-select for the
|
||||
`agents.defaults.models` allowlist (what shows up in `/model` and the model picker).
|
||||
|
||||
When configure starts from a provider auth choice, the default-model and
|
||||
allowlist pickers prefer that provider automatically. For paired providers such
|
||||
as Volcengine/BytePlus, the same preference also matches their coding-plan
|
||||
variants (`volcengine-plan/*`, `byteplus-plan/*`). If the preferred-provider
|
||||
filter would produce an empty list, configure falls back to the unfiltered
|
||||
catalog instead of showing a blank picker.
|
||||
|
||||
Tip: `openclaw config` without a subcommand opens the same wizard. Use
|
||||
`openclaw config get|set|unset` for non-interactive edits.
|
||||
|
||||
For web search, `openclaw configure --section web` lets you choose a provider
|
||||
and configure its credentials. Some providers also show provider-specific
|
||||
follow-up prompts:
|
||||
|
||||
- **Grok** can offer optional `x_search` setup with the same `XAI_API_KEY` and
|
||||
let you pick an `x_search` model.
|
||||
- **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs
|
||||
`api.moonshot.cn`) and the default Kimi web-search model.
|
||||
|
||||
Related:
|
||||
|
||||
- Gateway configuration reference: [Configuration](/gateway/configuration)
|
||||
- Config CLI: [Config](/cli/config)
|
||||
|
||||
## Options
|
||||
|
||||
- `--section <section>`: repeatable section filter
|
||||
|
||||
Available sections:
|
||||
|
||||
- `workspace`
|
||||
- `model`
|
||||
- `web`
|
||||
- `gateway`
|
||||
- `daemon`
|
||||
- `channels`
|
||||
- `plugins`
|
||||
- `skills`
|
||||
- `health`
|
||||
|
||||
Notes:
|
||||
|
||||
- Choosing where the Gateway runs always updates `gateway.mode`. You can select "Continue" without other sections if that is all you need.
|
||||
- Channel-oriented services (Slack/Discord/Matrix/Microsoft Teams) prompt for channel/room allowlists during setup. You can enter names or IDs; the wizard resolves names to IDs when possible.
|
||||
- If you run the daemon install step, token auth requires a token, and `gateway.auth.token` is SecretRef-managed, configure validates the SecretRef but does not persist resolved plaintext token values into supervisor service environment metadata.
|
||||
- If token auth requires a token and the configured token SecretRef is unresolved, configure blocks daemon install with actionable remediation guidance.
|
||||
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, configure blocks daemon install until mode is set explicitly.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
openclaw configure --section web
|
||||
openclaw configure --section model --section channels
|
||||
openclaw configure --section gateway --section daemon
|
||||
```
|
||||
167
openclaw/docs/cli/cron.md
Normal file
167
openclaw/docs/cli/cron.md
Normal file
|
|
@ -0,0 +1,167 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw cron` (schedule and run background jobs)"
|
||||
read_when:
|
||||
- You want scheduled jobs and wakeups
|
||||
- You’re debugging cron execution and logs
|
||||
title: "cron"
|
||||
---
|
||||
|
||||
# `openclaw cron`
|
||||
|
||||
Manage cron jobs for the Gateway scheduler.
|
||||
|
||||
Related:
|
||||
|
||||
- Cron jobs: [Cron jobs](/automation/cron-jobs)
|
||||
|
||||
Tip: run `openclaw cron --help` for the full command surface.
|
||||
|
||||
Note: isolated `cron add` jobs default to `--announce` delivery. Use `--no-deliver` to keep
|
||||
output internal. `--deliver` remains as a deprecated alias for `--announce`.
|
||||
|
||||
Note: cron-owned isolated runs expect a plain-text summary and the runner owns
|
||||
the final send path. `--no-deliver` keeps the run internal; it does not hand
|
||||
delivery back to the agent's message tool.
|
||||
|
||||
Note: one-shot (`--at`) jobs delete after success by default. Use `--keep-after-run` to keep them.
|
||||
|
||||
Note: `--session` supports `main`, `isolated`, `current`, and `session:<id>`.
|
||||
Use `current` to bind to the active session at creation time, or `session:<id>` for
|
||||
an explicit persistent session key.
|
||||
|
||||
Note: for one-shot CLI jobs, offset-less `--at` datetimes are treated as UTC unless you also pass
|
||||
`--tz <iana>`, which interprets that local wall-clock time in the given timezone.
|
||||
|
||||
Note: recurring jobs now use exponential retry backoff after consecutive errors (30s → 1m → 5m → 15m → 60m), then return to normal schedule after the next successful run.
|
||||
|
||||
Note: `openclaw cron run` now returns as soon as the manual run is queued for execution. Successful responses include `{ ok: true, enqueued: true, runId }`; use `openclaw cron runs --id <job-id>` to follow the eventual outcome.
|
||||
|
||||
Note: `openclaw cron run <job-id>` force-runs by default. Use `--due` to keep the
|
||||
older "only run if due" behavior.
|
||||
|
||||
Note: isolated cron turns suppress stale acknowledgement-only replies. If the
|
||||
first result is just an interim status update and no descendant subagent run is
|
||||
responsible for the eventual answer, cron re-prompts once for the real result
|
||||
before delivery.
|
||||
|
||||
Note: if an isolated cron run returns only the silent token (`NO_REPLY` /
|
||||
`no_reply`), cron suppresses direct outbound delivery and the fallback queued
|
||||
summary path as well, so nothing is posted back to chat.
|
||||
|
||||
Note: `cron add|edit --model ...` uses that selected allowed model for the job.
|
||||
If the model is not allowed, cron warns and falls back to the job's agent/default
|
||||
model selection instead. Configured fallback chains still apply, but a plain
|
||||
model override with no explicit per-job fallback list no longer appends the
|
||||
agent primary as a hidden extra retry target.
|
||||
|
||||
Note: isolated cron model precedence is Gmail-hook override first, then per-job
|
||||
`--model`, then any stored cron-session model override, then the normal
|
||||
agent/default selection.
|
||||
|
||||
Note: isolated cron fast mode follows the resolved live model selection. Model
|
||||
config `params.fastMode` applies by default, but a stored session `fastMode`
|
||||
override still wins over config.
|
||||
|
||||
Note: if an isolated run throws `LiveSessionModelSwitchError`, cron persists the
|
||||
switched provider/model (and switched auth profile override when present) before
|
||||
retrying. The outer retry loop is bounded to 2 switch retries after the initial
|
||||
attempt, then aborts instead of looping forever.
|
||||
|
||||
Note: failure notifications use `delivery.failureDestination` first, then
|
||||
global `cron.failureDestination`, and finally fall back to the job's primary
|
||||
announce target when no explicit failure destination is configured.
|
||||
|
||||
Note: retention/pruning is controlled in config:
|
||||
|
||||
- `cron.sessionRetention` (default `24h`) prunes completed isolated run sessions.
|
||||
- `cron.runLog.maxBytes` + `cron.runLog.keepLines` prune `~/.openclaw/cron/runs/<jobId>.jsonl`.
|
||||
|
||||
Upgrade note: if you have older cron jobs from before the current delivery/store format, run
|
||||
`openclaw doctor --fix`. Doctor now normalizes legacy cron fields (`jobId`, `schedule.cron`,
|
||||
top-level delivery fields including legacy `threadId`, payload `provider` delivery aliases) and migrates simple
|
||||
`notify: true` webhook fallback jobs to explicit webhook delivery when `cron.webhook` is
|
||||
configured.
|
||||
|
||||
## Common edits
|
||||
|
||||
Update delivery settings without changing the message:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel telegram --to "123456789"
|
||||
```
|
||||
|
||||
Disable delivery for an isolated job:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
Enable lightweight bootstrap context for an isolated job:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --light-context
|
||||
```
|
||||
|
||||
Announce to a specific channel:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
```
|
||||
|
||||
Create an isolated job with lightweight bootstrap context:
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
--name "Lightweight morning brief" \
|
||||
--cron "0 7 * * *" \
|
||||
--session isolated \
|
||||
--message "Summarize overnight updates." \
|
||||
--light-context \
|
||||
--no-deliver
|
||||
```
|
||||
|
||||
`--light-context` applies to isolated agent-turn jobs only. For cron runs, lightweight mode keeps bootstrap context empty instead of injecting the full workspace bootstrap set.
|
||||
|
||||
Delivery ownership note:
|
||||
|
||||
- Cron-owned isolated jobs always route final user-visible delivery through the
|
||||
cron runner (`announce`, `webhook`, or internal-only `none`).
|
||||
- If the task mentions messaging some external recipient, the agent should
|
||||
describe the intended destination in its result instead of trying to send it
|
||||
directly.
|
||||
|
||||
## Common admin commands
|
||||
|
||||
Manual run:
|
||||
|
||||
```bash
|
||||
openclaw cron run <job-id>
|
||||
openclaw cron run <job-id> --due
|
||||
openclaw cron runs --id <job-id> --limit 50
|
||||
```
|
||||
|
||||
Agent/session retargeting:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --agent ops
|
||||
openclaw cron edit <job-id> --clear-agent
|
||||
openclaw cron edit <job-id> --session current
|
||||
openclaw cron edit <job-id> --session "session:daily-brief"
|
||||
```
|
||||
|
||||
Delivery tweaks:
|
||||
|
||||
```bash
|
||||
openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
|
||||
openclaw cron edit <job-id> --best-effort-deliver
|
||||
openclaw cron edit <job-id> --no-best-effort-deliver
|
||||
openclaw cron edit <job-id> --no-deliver
|
||||
```
|
||||
|
||||
Failure-delivery note:
|
||||
|
||||
- `delivery.failureDestination` is supported for isolated jobs.
|
||||
- Main-session jobs may only use `delivery.failureDestination` when primary
|
||||
delivery mode is `webhook`.
|
||||
- If you do not set any failure destination and the job already announces to a
|
||||
channel, failure notifications reuse that same announce target.
|
||||
57
openclaw/docs/cli/daemon.md
Normal file
57
openclaw/docs/cli/daemon.md
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw daemon` (legacy alias for gateway service management)"
|
||||
read_when:
|
||||
- You still use `openclaw daemon ...` in scripts
|
||||
- You need service lifecycle commands (install/start/stop/restart/status)
|
||||
title: "daemon"
|
||||
---
|
||||
|
||||
# `openclaw daemon`
|
||||
|
||||
Legacy alias for Gateway service management commands.
|
||||
|
||||
`openclaw daemon ...` maps to the same service control surface as `openclaw gateway ...` service commands.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw daemon status
|
||||
openclaw daemon install
|
||||
openclaw daemon start
|
||||
openclaw daemon stop
|
||||
openclaw daemon restart
|
||||
openclaw daemon uninstall
|
||||
```
|
||||
|
||||
## Subcommands
|
||||
|
||||
- `status`: show service install state and probe Gateway health
|
||||
- `install`: install service (`launchd`/`systemd`/`schtasks`)
|
||||
- `uninstall`: remove service
|
||||
- `start`: start service
|
||||
- `stop`: stop service
|
||||
- `restart`: restart service
|
||||
|
||||
## Common options
|
||||
|
||||
- `status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
|
||||
- `install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
|
||||
- lifecycle (`uninstall|start|stop|restart`): `--json`
|
||||
|
||||
Notes:
|
||||
|
||||
- `status` resolves configured auth SecretRefs for probe auth when possible.
|
||||
- If a required auth SecretRef is unresolved in this command path, `daemon status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
|
||||
- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
|
||||
- `status --deep` adds a best-effort system-level service scan. When it finds other gateway-like services, human output prints cleanup hints and warns that one gateway per machine is still the normal recommendation.
|
||||
- On Linux systemd installs, `status` token-drift checks include both `Environment=` and `EnvironmentFile=` unit sources.
|
||||
- Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
|
||||
- If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
|
||||
- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
|
||||
- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed.
|
||||
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
|
||||
- If you intentionally run multiple gateways on one host, isolate ports, config/state, and workspaces; see [/gateway#multiple-gateways-same-host](/gateway#multiple-gateways-same-host).
|
||||
|
||||
## Prefer
|
||||
|
||||
Use [`openclaw gateway`](/cli/gateway) for current docs and examples.
|
||||
22
openclaw/docs/cli/dashboard.md
Normal file
22
openclaw/docs/cli/dashboard.md
Normal file
|
|
@ -0,0 +1,22 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw dashboard` (open the Control UI)"
|
||||
read_when:
|
||||
- You want to open the Control UI with your current token
|
||||
- You want to print the URL without launching a browser
|
||||
title: "dashboard"
|
||||
---
|
||||
|
||||
# `openclaw dashboard`
|
||||
|
||||
Open the Control UI using your current auth.
|
||||
|
||||
```bash
|
||||
openclaw dashboard
|
||||
openclaw dashboard --no-open
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `dashboard` resolves configured `gateway.auth.token` SecretRefs when possible.
|
||||
- For SecretRef-managed tokens (resolved or unresolved), `dashboard` prints/copies/opens a non-tokenized URL to avoid exposing external secrets in terminal output, clipboard history, or browser-launch arguments.
|
||||
- If `gateway.auth.token` is SecretRef-managed but unresolved in this command path, the command prints a non-tokenized URL and explicit remediation guidance instead of embedding an invalid token placeholder.
|
||||
180
openclaw/docs/cli/devices.md
Normal file
180
openclaw/docs/cli/devices.md
Normal file
|
|
@ -0,0 +1,180 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw devices` (device pairing + token rotation/revocation)"
|
||||
read_when:
|
||||
- You are approving device pairing requests
|
||||
- You need to rotate or revoke device tokens
|
||||
title: "devices"
|
||||
---
|
||||
|
||||
# `openclaw devices`
|
||||
|
||||
Manage device pairing requests and device-scoped tokens.
|
||||
|
||||
## Commands
|
||||
|
||||
### `openclaw devices list`
|
||||
|
||||
List pending pairing requests and paired devices.
|
||||
|
||||
```
|
||||
openclaw devices list
|
||||
openclaw devices list --json
|
||||
```
|
||||
|
||||
Pending request output shows the requested access next to the device's current
|
||||
approved access when the device is already paired. This makes scope/role
|
||||
upgrades explicit instead of looking like the pairing was lost.
|
||||
|
||||
### `openclaw devices remove <deviceId>`
|
||||
|
||||
Remove one paired device entry.
|
||||
|
||||
When you are authenticated with a paired device token, non-admin callers can
|
||||
remove only **their own** device entry. Removing some other device requires
|
||||
`operator.admin`.
|
||||
|
||||
```
|
||||
openclaw devices remove <deviceId>
|
||||
openclaw devices remove <deviceId> --json
|
||||
```
|
||||
|
||||
### `openclaw devices clear --yes [--pending]`
|
||||
|
||||
Clear paired devices in bulk.
|
||||
|
||||
```
|
||||
openclaw devices clear --yes
|
||||
openclaw devices clear --yes --pending
|
||||
openclaw devices clear --yes --pending --json
|
||||
```
|
||||
|
||||
### `openclaw devices approve [requestId] [--latest]`
|
||||
|
||||
Approve a pending device pairing request by exact `requestId`. If `requestId`
|
||||
is omitted or `--latest` is passed, OpenClaw only prints the selected pending
|
||||
request and exits; rerun approval with the exact request ID after verifying
|
||||
the details.
|
||||
|
||||
Note: if a device retries pairing with changed auth details (role/scopes/public
|
||||
key), OpenClaw supersedes the previous pending entry and issues a new
|
||||
`requestId`. Run `openclaw devices list` right before approval to use the
|
||||
current ID.
|
||||
|
||||
If the device is already paired and asks for broader scopes or a broader role,
|
||||
OpenClaw keeps the existing approval in place and creates a new pending upgrade
|
||||
request. Review the `Requested` vs `Approved` columns in `openclaw devices list`
|
||||
or use `openclaw devices approve --latest` to preview the exact upgrade before
|
||||
approving it.
|
||||
|
||||
```
|
||||
openclaw devices approve
|
||||
openclaw devices approve <requestId>
|
||||
openclaw devices approve --latest
|
||||
```
|
||||
|
||||
### `openclaw devices reject <requestId>`
|
||||
|
||||
Reject a pending device pairing request.
|
||||
|
||||
```
|
||||
openclaw devices reject <requestId>
|
||||
```
|
||||
|
||||
### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`
|
||||
|
||||
Rotate a device token for a specific role (optionally updating scopes).
|
||||
The target role must already exist in that device's approved pairing contract;
|
||||
rotation cannot mint a new unapproved role.
|
||||
If you omit `--scope`, later reconnects with the stored rotated token reuse that
|
||||
token's cached approved scopes. If you pass explicit `--scope` values, those
|
||||
become the stored scope set for future cached-token reconnects.
|
||||
Non-admin paired-device callers can rotate only their **own** device token.
|
||||
Also, any explicit `--scope` values must stay within the caller session's own
|
||||
operator scopes; rotation cannot mint a broader operator token than the caller
|
||||
already has.
|
||||
|
||||
```
|
||||
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
|
||||
```
|
||||
|
||||
Returns the new token payload as JSON.
|
||||
|
||||
### `openclaw devices revoke --device <id> --role <role>`
|
||||
|
||||
Revoke a device token for a specific role.
|
||||
|
||||
Non-admin paired-device callers can revoke only their **own** device token.
|
||||
Revoking some other device's token requires `operator.admin`.
|
||||
|
||||
```
|
||||
openclaw devices revoke --device <deviceId> --role node
|
||||
```
|
||||
|
||||
Returns the revoke result as JSON.
|
||||
|
||||
## Common options
|
||||
|
||||
- `--url <url>`: Gateway WebSocket URL (defaults to `gateway.remote.url` when configured).
|
||||
- `--token <token>`: Gateway token (if required).
|
||||
- `--password <password>`: Gateway password (password auth).
|
||||
- `--timeout <ms>`: RPC timeout.
|
||||
- `--json`: JSON output (recommended for scripting).
|
||||
|
||||
Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
|
||||
Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
|
||||
|
||||
## Notes
|
||||
|
||||
- Token rotation returns a new token (sensitive). Treat it like a secret.
|
||||
- These commands require `operator.pairing` (or `operator.admin`) scope.
|
||||
- Token rotation stays inside the approved pairing role set and approved scope
|
||||
baseline for that device. A stray cached token entry does not grant a new
|
||||
rotate target.
|
||||
- For paired-device token sessions, cross-device management is admin-only:
|
||||
`remove`, `rotate`, and `revoke` are self-only unless the caller has
|
||||
`operator.admin`.
|
||||
- `devices clear` is intentionally gated by `--yes`.
|
||||
- If pairing scope is unavailable on local loopback (and no explicit `--url` is passed), list/approve can use a local pairing fallback.
|
||||
- `devices approve` requires an explicit request ID before minting tokens; omitting `requestId` or passing `--latest` only previews the newest pending request.
|
||||
|
||||
## Token drift recovery checklist
|
||||
|
||||
Use this when Control UI or other clients keep failing with `AUTH_TOKEN_MISMATCH` or `AUTH_DEVICE_TOKEN_MISMATCH`.
|
||||
|
||||
1. Confirm current gateway token source:
|
||||
|
||||
```bash
|
||||
openclaw config get gateway.auth.token
|
||||
```
|
||||
|
||||
2. List paired devices and identify the affected device id:
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
```
|
||||
|
||||
3. Rotate operator token for the affected device:
|
||||
|
||||
```bash
|
||||
openclaw devices rotate --device <deviceId> --role operator
|
||||
```
|
||||
|
||||
4. If rotation is not enough, remove stale pairing and approve again:
|
||||
|
||||
```bash
|
||||
openclaw devices remove <deviceId>
|
||||
openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
|
||||
5. Retry client connection with the current shared token/password.
|
||||
|
||||
Notes:
|
||||
|
||||
- Normal reconnect auth precedence is explicit shared token/password first, then explicit `deviceToken`, then stored device token, then bootstrap token.
|
||||
- Trusted `AUTH_TOKEN_MISMATCH` recovery can temporarily send both the shared token and the stored device token together for the one bounded retry.
|
||||
|
||||
Related:
|
||||
|
||||
- [Dashboard auth troubleshooting](/web/dashboard#if-you-see-unauthorized-1008)
|
||||
- [Gateway troubleshooting](/gateway/troubleshooting#dashboard-control-ui-connectivity)
|
||||
63
openclaw/docs/cli/directory.md
Normal file
63
openclaw/docs/cli/directory.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw directory` (self, peers, groups)"
|
||||
read_when:
|
||||
- You want to look up contacts/groups/self ids for a channel
|
||||
- You are developing a channel directory adapter
|
||||
title: "directory"
|
||||
---
|
||||
|
||||
# `openclaw directory`
|
||||
|
||||
Directory lookups for channels that support it (contacts/peers, groups, and “me”).
|
||||
|
||||
## Common flags
|
||||
|
||||
- `--channel <name>`: channel id/alias (required when multiple channels are configured; auto when only one is configured)
|
||||
- `--account <id>`: account id (default: channel default)
|
||||
- `--json`: output JSON
|
||||
|
||||
## Notes
|
||||
|
||||
- `directory` is meant to help you find IDs you can paste into other commands (especially `openclaw message send --target ...`).
|
||||
- For many channels, results are config-backed (allowlists / configured groups) rather than a live provider directory.
|
||||
- Default output is `id` (and sometimes `name`) separated by a tab; use `--json` for scripting.
|
||||
|
||||
## Using results with `message send`
|
||||
|
||||
```bash
|
||||
openclaw directory peers list --channel slack --query "U0"
|
||||
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"
|
||||
```
|
||||
|
||||
## ID formats (by channel)
|
||||
|
||||
- WhatsApp: `+15551234567` (DM), `1234567890-1234567890@g.us` (group)
|
||||
- Telegram: `@username` or numeric chat id; groups are numeric ids
|
||||
- Slack: `user:U…` and `channel:C…`
|
||||
- Discord: `user:<id>` and `channel:<id>`
|
||||
- Matrix (plugin): `user:@user:server`, `room:!roomId:server`, or `#alias:server`
|
||||
- Microsoft Teams (plugin): `user:<id>` and `conversation:<id>`
|
||||
- Zalo (plugin): user id (Bot API)
|
||||
- Zalo Personal / `zalouser` (plugin): thread id (DM/group) from `zca` (`me`, `friend list`, `group list`)
|
||||
|
||||
## Self ("me")
|
||||
|
||||
```bash
|
||||
openclaw directory self --channel zalouser
|
||||
```
|
||||
|
||||
## Peers (contacts/users)
|
||||
|
||||
```bash
|
||||
openclaw directory peers list --channel zalouser
|
||||
openclaw directory peers list --channel zalouser --query "name"
|
||||
openclaw directory peers list --channel zalouser --limit 50
|
||||
```
|
||||
|
||||
## Groups
|
||||
|
||||
```bash
|
||||
openclaw directory groups list --channel zalouser
|
||||
openclaw directory groups list --channel zalouser --query "work"
|
||||
openclaw directory groups members --channel zalouser --group-id <id>
|
||||
```
|
||||
48
openclaw/docs/cli/dns.md
Normal file
48
openclaw/docs/cli/dns.md
Normal file
|
|
@ -0,0 +1,48 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw dns` (wide-area discovery helpers)"
|
||||
read_when:
|
||||
- You want wide-area discovery (DNS-SD) via Tailscale + CoreDNS
|
||||
- You’re setting up split DNS for a custom discovery domain (example: openclaw.internal)
|
||||
title: "dns"
|
||||
---
|
||||
|
||||
# `openclaw dns`
|
||||
|
||||
DNS helpers for wide-area discovery (Tailscale + CoreDNS). Currently focused on macOS + Homebrew CoreDNS.
|
||||
|
||||
Related:
|
||||
|
||||
- Gateway discovery: [Discovery](/gateway/discovery)
|
||||
- Wide-area discovery config: [Configuration](/gateway/configuration)
|
||||
|
||||
## Setup
|
||||
|
||||
```bash
|
||||
openclaw dns setup
|
||||
openclaw dns setup --domain openclaw.internal
|
||||
openclaw dns setup --apply
|
||||
```
|
||||
|
||||
## `dns setup`
|
||||
|
||||
Plan or apply CoreDNS setup for unicast DNS-SD discovery.
|
||||
|
||||
Options:
|
||||
|
||||
- `--domain <domain>`: wide-area discovery domain (for example `openclaw.internal`)
|
||||
- `--apply`: install or update CoreDNS config and restart the service (requires sudo; macOS only)
|
||||
|
||||
What it shows:
|
||||
|
||||
- resolved discovery domain
|
||||
- zone file path
|
||||
- current tailnet IPs
|
||||
- recommended `openclaw.json` discovery config
|
||||
- the Tailscale Split DNS nameserver/domain values to set
|
||||
|
||||
Notes:
|
||||
|
||||
- Without `--apply`, the command is a planning helper only and prints the recommended setup.
|
||||
- If `--domain` is omitted, OpenClaw uses `discovery.wideArea.domain` from config.
|
||||
- `--apply` currently supports macOS only and expects Homebrew CoreDNS.
|
||||
- `--apply` bootstraps the zone file if needed, ensures the CoreDNS import stanza exists, and restarts the `coredns` brew service.
|
||||
28
openclaw/docs/cli/docs.md
Normal file
28
openclaw/docs/cli/docs.md
Normal file
|
|
@ -0,0 +1,28 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw docs` (search the live docs index)"
|
||||
read_when:
|
||||
- You want to search the live OpenClaw docs from the terminal
|
||||
title: "docs"
|
||||
---
|
||||
|
||||
# `openclaw docs`
|
||||
|
||||
Search the live docs index.
|
||||
|
||||
Arguments:
|
||||
|
||||
- `[query...]`: search terms to send to the live docs index
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw docs
|
||||
openclaw docs browser existing-session
|
||||
openclaw docs sandbox allowHostControl
|
||||
openclaw docs gateway token secretref
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- With no query, `openclaw docs` opens the live docs search entrypoint.
|
||||
- Multi-word queries are passed through as one search request.
|
||||
63
openclaw/docs/cli/doctor.md
Normal file
63
openclaw/docs/cli/doctor.md
Normal file
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw doctor` (health checks + guided repairs)"
|
||||
read_when:
|
||||
- You have connectivity/auth issues and want guided fixes
|
||||
- You updated and want a sanity check
|
||||
title: "doctor"
|
||||
---
|
||||
|
||||
# `openclaw doctor`
|
||||
|
||||
Health checks + quick fixes for the gateway and channels.
|
||||
|
||||
Related:
|
||||
|
||||
- Troubleshooting: [Troubleshooting](/gateway/troubleshooting)
|
||||
- Security audit: [Security](/gateway/security)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
openclaw doctor --repair
|
||||
openclaw doctor --deep
|
||||
openclaw doctor --repair --non-interactive
|
||||
openclaw doctor --generate-gateway-token
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--no-workspace-suggestions`: disable workspace memory/search suggestions
|
||||
- `--yes`: accept defaults without prompting
|
||||
- `--repair`: apply recommended repairs without prompting
|
||||
- `--fix`: alias for `--repair`
|
||||
- `--force`: apply aggressive repairs, including overwriting custom service config when needed
|
||||
- `--non-interactive`: run without prompts; safe migrations only
|
||||
- `--generate-gateway-token`: generate and configure a gateway token
|
||||
- `--deep`: scan system services for extra gateway installs
|
||||
|
||||
Notes:
|
||||
|
||||
- Interactive prompts (like keychain/OAuth fixes) only run when stdin is a TTY and `--non-interactive` is **not** set. Headless runs (cron, Telegram, no terminal) will skip prompts.
|
||||
- `--fix` (alias for `--repair`) writes a backup to `~/.openclaw/openclaw.json.bak` and drops unknown config keys, listing each removal.
|
||||
- State integrity checks now detect orphan transcript files in the sessions directory and can archive them as `.deleted.<timestamp>` to reclaim space safely.
|
||||
- Doctor also scans `~/.openclaw/cron/jobs.json` (or `cron.store`) for legacy cron job shapes and can rewrite them in place before the scheduler has to auto-normalize them at runtime.
|
||||
- Doctor auto-migrates legacy flat Talk config (`talk.voiceId`, `talk.modelId`, and friends) into `talk.provider` + `talk.providers.<provider>`.
|
||||
- Repeat `doctor --fix` runs no longer report/apply Talk normalization when the only difference is object key order.
|
||||
- Doctor includes a memory-search readiness check and can recommend `openclaw configure --section model` when embedding credentials are missing.
|
||||
- If sandbox mode is enabled but Docker is unavailable, doctor reports a high-signal warning with remediation (`install Docker` or `openclaw config set agents.defaults.sandbox.mode off`).
|
||||
- If `gateway.auth.token`/`gateway.auth.password` are SecretRef-managed and unavailable in the current command path, doctor reports a read-only warning and does not write plaintext fallback credentials.
|
||||
- If channel SecretRef inspection fails in a fix path, doctor continues and reports a warning instead of exiting early.
|
||||
- Telegram `allowFrom` username auto-resolution (`doctor --fix`) requires a resolvable Telegram token in the current command path. If token inspection is unavailable, doctor reports a warning and skips auto-resolution for that pass.
|
||||
|
||||
## macOS: `launchctl` env overrides
|
||||
|
||||
If you previously ran `launchctl setenv OPENCLAW_GATEWAY_TOKEN ...` (or `...PASSWORD`), that value overrides your config file and can cause persistent “unauthorized” errors.
|
||||
|
||||
```bash
|
||||
launchctl getenv OPENCLAW_GATEWAY_TOKEN
|
||||
launchctl getenv OPENCLAW_GATEWAY_PASSWORD
|
||||
|
||||
launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
|
||||
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD
|
||||
```
|
||||
18
openclaw/docs/cli/flows.md
Normal file
18
openclaw/docs/cli/flows.md
Normal file
|
|
@ -0,0 +1,18 @@
|
|||
---
|
||||
summary: "Redirect: flow commands live under `openclaw tasks flow`"
|
||||
read_when:
|
||||
- You encounter openclaw flows in older docs or release notes
|
||||
title: "flows (redirect)"
|
||||
---
|
||||
|
||||
# `openclaw tasks flow`
|
||||
|
||||
Flow commands are subcommands of `openclaw tasks`, not a standalone `flows` command.
|
||||
|
||||
```bash
|
||||
openclaw tasks flow list [--json]
|
||||
openclaw tasks flow show <lookup>
|
||||
openclaw tasks flow cancel <lookup>
|
||||
```
|
||||
|
||||
For full documentation see [Task Flow](/automation/taskflow) and the [tasks CLI reference](/cli/index#tasks).
|
||||
313
openclaw/docs/cli/gateway.md
Normal file
313
openclaw/docs/cli/gateway.md
Normal file
|
|
@ -0,0 +1,313 @@
|
|||
---
|
||||
summary: "OpenClaw Gateway CLI (`openclaw gateway`) — run, query, and discover gateways"
|
||||
read_when:
|
||||
- Running the Gateway from the CLI (dev or servers)
|
||||
- Debugging Gateway auth, bind modes, and connectivity
|
||||
- Discovering gateways via Bonjour (local + wide-area DNS-SD)
|
||||
title: "gateway"
|
||||
---
|
||||
|
||||
# Gateway CLI
|
||||
|
||||
The Gateway is OpenClaw’s WebSocket server (channels, nodes, sessions, hooks).
|
||||
|
||||
Subcommands in this page live under `openclaw gateway …`.
|
||||
|
||||
Related docs:
|
||||
|
||||
- [/gateway/bonjour](/gateway/bonjour)
|
||||
- [/gateway/discovery](/gateway/discovery)
|
||||
- [/gateway/configuration](/gateway/configuration)
|
||||
|
||||
## Run the Gateway
|
||||
|
||||
Run a local Gateway process:
|
||||
|
||||
```bash
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
Foreground alias:
|
||||
|
||||
```bash
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.openclaw/openclaw.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
|
||||
- `openclaw onboard --mode local` and `openclaw setup` are expected to write `gateway.mode=local`. If the file exists but `gateway.mode` is missing, treat that as a broken or clobbered config and repair it instead of assuming local mode implicitly.
|
||||
- If the file exists and `gateway.mode` is missing, the Gateway treats that as suspicious config damage and refuses to “guess local” for you.
|
||||
- Binding beyond loopback without auth is blocked (safety guardrail).
|
||||
- `SIGUSR1` triggers an in-process restart when authorized (`commands.restart` is enabled by default; set `commands.restart: false` to block manual restart, while gateway tool/config apply/update remain allowed).
|
||||
- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.
|
||||
|
||||
### Options
|
||||
|
||||
- `--port <port>`: WebSocket port (default comes from config/env; usually `18789`).
|
||||
- `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode.
|
||||
- `--auth <token|password>`: auth mode override.
|
||||
- `--token <token>`: token override (also sets `OPENCLAW_GATEWAY_TOKEN` for the process).
|
||||
- `--password <password>`: password override. Warning: inline passwords can be exposed in local process listings.
|
||||
- `--password-file <path>`: read the gateway password from a file.
|
||||
- `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.
|
||||
- `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.
|
||||
- `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config. This bypasses the startup guard for ad-hoc/dev bootstrap only; it does not write or repair the config file.
|
||||
- `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).
|
||||
- `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).
|
||||
- `--force`: kill any existing listener on the selected port before starting.
|
||||
- `--verbose`: verbose logs.
|
||||
- `--cli-backend-logs`: only show CLI backend logs in the console (and enable stdout/stderr).
|
||||
- `--ws-log <auto|full|compact>`: websocket log style (default `auto`).
|
||||
- `--compact`: alias for `--ws-log compact`.
|
||||
- `--raw-stream`: log raw model stream events to jsonl.
|
||||
- `--raw-stream-path <path>`: raw stream jsonl path.
|
||||
|
||||
## Query a running Gateway
|
||||
|
||||
All query commands use WebSocket RPC.
|
||||
|
||||
Output modes:
|
||||
|
||||
- Default: human-readable (colored in TTY).
|
||||
- `--json`: machine-readable JSON (no styling/spinner).
|
||||
- `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.
|
||||
|
||||
Shared options (where supported):
|
||||
|
||||
- `--url <url>`: Gateway WebSocket URL.
|
||||
- `--token <token>`: Gateway token.
|
||||
- `--password <password>`: Gateway password.
|
||||
- `--timeout <ms>`: timeout/budget (varies per command).
|
||||
- `--expect-final`: wait for a “final” response (agent calls).
|
||||
|
||||
Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
|
||||
Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
|
||||
|
||||
### `gateway health`
|
||||
|
||||
```bash
|
||||
openclaw gateway health --url ws://127.0.0.1:18789
|
||||
```
|
||||
|
||||
### `gateway usage-cost`
|
||||
|
||||
Fetch usage-cost summaries from session logs.
|
||||
|
||||
```bash
|
||||
openclaw gateway usage-cost
|
||||
openclaw gateway usage-cost --days 7
|
||||
openclaw gateway usage-cost --json
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--days <days>`: number of days to include (default `30`).
|
||||
|
||||
### `gateway status`
|
||||
|
||||
`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional probe of connectivity/auth capability.
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
openclaw gateway status --json
|
||||
openclaw gateway status --require-rpc
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--url <url>`: add an explicit probe target. Configured remote + localhost are still probed.
|
||||
- `--token <token>`: token auth for the probe.
|
||||
- `--password <password>`: password auth for the probe.
|
||||
- `--timeout <ms>`: probe timeout (default `10000`).
|
||||
- `--no-probe`: skip the connectivity probe (service-only view).
|
||||
- `--deep`: scan system-level services too.
|
||||
- `--require-rpc`: upgrade the default connectivity probe to a read probe and exit non-zero when that read probe fails. Cannot be combined with `--no-probe`.
|
||||
|
||||
Notes:
|
||||
|
||||
- `gateway status` stays available for diagnostics even when the local CLI config is missing or invalid.
|
||||
- Default `gateway status` proves service state, WebSocket connect, and the auth capability visible at handshake time. It does not prove read/write/admin operations.
|
||||
- `gateway status` resolves configured auth SecretRefs for probe auth when possible.
|
||||
- If a required auth SecretRef is unresolved in this command path, `gateway status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
|
||||
- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
|
||||
- Use `--require-rpc` in scripts and automation when a listening service is not enough and you need read-scope RPC calls to be healthy too.
|
||||
- `--deep` adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
|
||||
- Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.
|
||||
- On Linux systemd installs, service auth drift checks read both `Environment=` and `EnvironmentFile=` values from the unit (including `%h`, quoted paths, multiple files, and optional `-` files).
|
||||
- Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
|
||||
- If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
|
||||
|
||||
### `gateway probe`
|
||||
|
||||
`gateway probe` is the “debug everything” command. It always probes:
|
||||
|
||||
- your configured remote gateway (if set), and
|
||||
- localhost (loopback) **even if remote is configured**.
|
||||
|
||||
If you pass `--url`, that explicit target is added ahead of both. Human output labels the
|
||||
targets as:
|
||||
|
||||
- `URL (explicit)`
|
||||
- `Remote (configured)` or `Remote (configured, inactive)`
|
||||
- `Local loopback`
|
||||
|
||||
If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
|
||||
|
||||
```bash
|
||||
openclaw gateway probe
|
||||
openclaw gateway probe --json
|
||||
```
|
||||
|
||||
Interpretation:
|
||||
|
||||
- `Reachable: yes` means at least one target accepted a WebSocket connect.
|
||||
- `Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only` reports what the probe could prove about auth. It is separate from reachability.
|
||||
- `Read probe: ok` means read-scope detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded.
|
||||
- `Read probe: limited - missing scope: operator.read` means connect succeeded but read-scope RPC is limited. This is reported as **degraded** reachability, not full failure.
|
||||
- Exit code is non-zero only when no probed target is reachable.
|
||||
|
||||
JSON notes (`--json`):
|
||||
|
||||
- Top level:
|
||||
- `ok`: at least one target is reachable.
|
||||
- `degraded`: at least one target had scope-limited detail RPC.
|
||||
- `capability`: best capability seen across reachable targets (`read_only`, `write_capable`, `admin_capable`, `pairing_pending`, `connected_no_operator_scope`, or `unknown`).
|
||||
- `primaryTargetId`: best target to treat as the active winner in this order: explicit URL, SSH tunnel, configured remote, then local loopback.
|
||||
- `warnings[]`: best-effort warning records with `code`, `message`, and optional `targetIds`.
|
||||
- `network`: local loopback/tailnet URL hints derived from current config and host networking.
|
||||
- `discovery.timeoutMs` and `discovery.count`: the actual discovery budget/result count used for this probe pass.
|
||||
- Per target (`targets[].connect`):
|
||||
- `ok`: reachability after connect + degraded classification.
|
||||
- `rpcOk`: full detail RPC success.
|
||||
- `scopeLimited`: detail RPC failed due to missing operator scope.
|
||||
- Per target (`targets[].auth`):
|
||||
- `role`: auth role reported in `hello-ok` when available.
|
||||
- `scopes`: granted scopes reported in `hello-ok` when available.
|
||||
- `capability`: the surfaced auth capability classification for that target.
|
||||
|
||||
Common warning codes:
|
||||
|
||||
- `ssh_tunnel_failed`: SSH tunnel setup failed; the command fell back to direct probes.
|
||||
- `multiple_gateways`: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
|
||||
- `auth_secretref_unresolved`: a configured auth SecretRef could not be resolved for a failed target.
|
||||
- `probe_scope_limited`: WebSocket connect succeeded, but the read probe was limited by missing `operator.read`.
|
||||
|
||||
#### Remote over SSH (Mac app parity)
|
||||
|
||||
The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
|
||||
|
||||
CLI equivalent:
|
||||
|
||||
```bash
|
||||
openclaw gateway probe --ssh user@gateway-host
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).
|
||||
- `--ssh-identity <path>`: identity file.
|
||||
- `--ssh-auto`: pick the first discovered gateway host as SSH target from the resolved
|
||||
discovery endpoint (`local.` plus the configured wide-area domain, if any). TXT-only
|
||||
hints are ignored.
|
||||
|
||||
Config (optional, used as defaults):
|
||||
|
||||
- `gateway.remote.sshTarget`
|
||||
- `gateway.remote.sshIdentity`
|
||||
|
||||
### `gateway call <method>`
|
||||
|
||||
Low-level RPC helper.
|
||||
|
||||
```bash
|
||||
openclaw gateway call status
|
||||
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--params <json>`: JSON object string for params (default `{}`)
|
||||
- `--url <url>`
|
||||
- `--token <token>`
|
||||
- `--password <password>`
|
||||
- `--timeout <ms>`
|
||||
- `--expect-final`
|
||||
- `--json`
|
||||
|
||||
Notes:
|
||||
|
||||
- `--params` must be valid JSON.
|
||||
- `--expect-final` is mainly for agent-style RPCs that stream intermediate events before a final payload.
|
||||
|
||||
## Manage the Gateway service
|
||||
|
||||
```bash
|
||||
openclaw gateway install
|
||||
openclaw gateway start
|
||||
openclaw gateway stop
|
||||
openclaw gateway restart
|
||||
openclaw gateway uninstall
|
||||
```
|
||||
|
||||
Command options:
|
||||
|
||||
- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
|
||||
- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
|
||||
- `gateway uninstall|start|stop|restart`: `--json`
|
||||
|
||||
Notes:
|
||||
|
||||
- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
|
||||
- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
|
||||
- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
|
||||
- For password auth on `gateway run`, prefer `OPENCLAW_GATEWAY_PASSWORD`, `--password-file`, or a SecretRef-backed `gateway.auth.password` over inline `--password`.
|
||||
- In inferred auth mode, shell-only `OPENCLAW_GATEWAY_PASSWORD` does not relax install token requirements; use durable config (`gateway.auth.password` or config `env`) when installing a managed service.
|
||||
- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
|
||||
- Lifecycle commands accept `--json` for scripting.
|
||||
|
||||
## Discover gateways (Bonjour)
|
||||
|
||||
`gateway discover` scans for Gateway beacons (`_openclaw-gw._tcp`).
|
||||
|
||||
- Multicast DNS-SD: `local.`
|
||||
- Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `openclaw.internal.`) and set up split DNS + a DNS server; see [/gateway/bonjour](/gateway/bonjour)
|
||||
|
||||
Only gateways with Bonjour discovery enabled (default) advertise the beacon.
|
||||
|
||||
Wide-Area discovery records include (TXT):
|
||||
|
||||
- `role` (gateway role hint)
|
||||
- `transport` (transport hint, e.g. `gateway`)
|
||||
- `gatewayPort` (WebSocket port, usually `18789`)
|
||||
- `sshPort` (optional; clients default SSH targets to `22` when it is absent)
|
||||
- `tailnetDns` (MagicDNS hostname, when available)
|
||||
- `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
|
||||
- `cliPath` (remote-install hint written to the wide-area zone)
|
||||
|
||||
### `gateway discover`
|
||||
|
||||
```bash
|
||||
openclaw gateway discover
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--timeout <ms>`: per-command timeout (browse/resolve); default `2000`.
|
||||
- `--json`: machine-readable output (also disables styling/spinner).
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw gateway discover --timeout 4000
|
||||
openclaw gateway discover --json | jq '.beacons[].wsUrl'
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- The CLI scans `local.` plus the configured wide-area domain when one is enabled.
|
||||
- `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only
|
||||
hints such as `lanHost` or `tailnetDns`.
|
||||
- On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when
|
||||
`discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort`
|
||||
stays optional there too.
|
||||
36
openclaw/docs/cli/health.md
Normal file
36
openclaw/docs/cli/health.md
Normal file
|
|
@ -0,0 +1,36 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw health` (gateway health snapshot via RPC)"
|
||||
read_when:
|
||||
- You want to quickly check the running Gateway’s health
|
||||
title: "health"
|
||||
---
|
||||
|
||||
# `openclaw health`
|
||||
|
||||
Fetch health from the running Gateway.
|
||||
|
||||
Options:
|
||||
|
||||
- `--json`: machine-readable output
|
||||
- `--timeout <ms>`: connection timeout in milliseconds (default `10000`)
|
||||
- `--verbose`: verbose logging
|
||||
- `--debug`: alias for `--verbose`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw health
|
||||
openclaw health --json
|
||||
openclaw health --timeout 2500
|
||||
openclaw health --verbose
|
||||
openclaw health --debug
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Default `openclaw health` asks the running gateway for its health snapshot. When the
|
||||
gateway already has a fresh cached snapshot, it can return that cached payload and
|
||||
refresh in the background.
|
||||
- `--verbose` forces a live probe, prints gateway connection details, and expands the
|
||||
human-readable output across all configured accounts and agents.
|
||||
- Output includes per-agent session stores when multiple agents are configured.
|
||||
337
openclaw/docs/cli/hooks.md
Normal file
337
openclaw/docs/cli/hooks.md
Normal file
|
|
@ -0,0 +1,337 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw hooks` (agent hooks)"
|
||||
read_when:
|
||||
- You want to manage agent hooks
|
||||
- You want to inspect hook availability or enable workspace hooks
|
||||
title: "hooks"
|
||||
---
|
||||
|
||||
# `openclaw hooks`
|
||||
|
||||
Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, and gateway startup).
|
||||
|
||||
Running `openclaw hooks` with no subcommand is equivalent to `openclaw hooks list`.
|
||||
|
||||
Related:
|
||||
|
||||
- Hooks: [Hooks](/automation/hooks)
|
||||
- Plugin hooks: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
|
||||
|
||||
## List All Hooks
|
||||
|
||||
```bash
|
||||
openclaw hooks list
|
||||
```
|
||||
|
||||
List all discovered hooks from workspace, managed, extra, and bundled directories.
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--eligible`: Show only eligible hooks (requirements met)
|
||||
- `--json`: Output as JSON
|
||||
- `-v, --verbose`: Show detailed information including missing requirements
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
Hooks (4/4 ready)
|
||||
|
||||
Ready:
|
||||
🚀 boot-md ✓ - Run BOOT.md on gateway startup
|
||||
📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
|
||||
📝 command-logger ✓ - Log all command events to a centralized audit file
|
||||
💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
|
||||
```
|
||||
|
||||
**Example (verbose):**
|
||||
|
||||
```bash
|
||||
openclaw hooks list --verbose
|
||||
```
|
||||
|
||||
Shows missing requirements for ineligible hooks.
|
||||
|
||||
**Example (JSON):**
|
||||
|
||||
```bash
|
||||
openclaw hooks list --json
|
||||
```
|
||||
|
||||
Returns structured JSON for programmatic use.
|
||||
|
||||
## Get Hook Information
|
||||
|
||||
```bash
|
||||
openclaw hooks info <name>
|
||||
```
|
||||
|
||||
Show detailed information about a specific hook.
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>`: Hook name or hook key (e.g., `session-memory`)
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--json`: Output as JSON
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
openclaw hooks info session-memory
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
💾 session-memory ✓ Ready
|
||||
|
||||
Save session context to memory when /new or /reset command is issued
|
||||
|
||||
Details:
|
||||
Source: openclaw-bundled
|
||||
Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
|
||||
Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
|
||||
Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
|
||||
Events: command:new, command:reset
|
||||
|
||||
Requirements:
|
||||
Config: ✓ workspace.dir
|
||||
```
|
||||
|
||||
## Check Hooks Eligibility
|
||||
|
||||
```bash
|
||||
openclaw hooks check
|
||||
```
|
||||
|
||||
Show summary of hook eligibility status (how many are ready vs. not ready).
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--json`: Output as JSON
|
||||
|
||||
**Example output:**
|
||||
|
||||
```
|
||||
Hooks Status
|
||||
|
||||
Total hooks: 4
|
||||
Ready: 4
|
||||
Not ready: 0
|
||||
```
|
||||
|
||||
## Enable a Hook
|
||||
|
||||
```bash
|
||||
openclaw hooks enable <name>
|
||||
```
|
||||
|
||||
Enable a specific hook by adding it to your config (`~/.openclaw/openclaw.json` by default).
|
||||
|
||||
**Note:** Workspace hooks are disabled by default until enabled here or in config. Hooks managed by plugins show `plugin:<id>` in `openclaw hooks list` and can’t be enabled/disabled here. Enable/disable the plugin instead.
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>`: Hook name (e.g., `session-memory`)
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
openclaw hooks enable session-memory
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
✓ Enabled hook: 💾 session-memory
|
||||
```
|
||||
|
||||
**What it does:**
|
||||
|
||||
- Checks if hook exists and is eligible
|
||||
- Updates `hooks.internal.entries.<name>.enabled = true` in your config
|
||||
- Saves config to disk
|
||||
|
||||
If the hook came from `<workspace>/hooks/`, this opt-in step is required before
|
||||
the Gateway will load it.
|
||||
|
||||
**After enabling:**
|
||||
|
||||
- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
|
||||
|
||||
## Disable a Hook
|
||||
|
||||
```bash
|
||||
openclaw hooks disable <name>
|
||||
```
|
||||
|
||||
Disable a specific hook by updating your config.
|
||||
|
||||
**Arguments:**
|
||||
|
||||
- `<name>`: Hook name (e.g., `command-logger`)
|
||||
|
||||
**Example:**
|
||||
|
||||
```bash
|
||||
openclaw hooks disable command-logger
|
||||
```
|
||||
|
||||
**Output:**
|
||||
|
||||
```
|
||||
⏸ Disabled hook: 📝 command-logger
|
||||
```
|
||||
|
||||
**After disabling:**
|
||||
|
||||
- Restart the gateway so hooks reload
|
||||
|
||||
## Notes
|
||||
|
||||
- `openclaw hooks list --json`, `info --json`, and `check --json` write structured JSON directly to stdout.
|
||||
- Plugin-managed hooks cannot be enabled or disabled here; enable or disable the owning plugin instead.
|
||||
|
||||
## Install Hook Packs
|
||||
|
||||
```bash
|
||||
openclaw plugins install <package> # ClawHub first, then npm
|
||||
openclaw plugins install <package> --pin # pin version
|
||||
openclaw plugins install <path> # local path
|
||||
```
|
||||
|
||||
Install hook packs through the unified plugins installer.
|
||||
|
||||
`openclaw hooks install` still works as a compatibility alias, but it prints a
|
||||
deprecation warning and forwards to `openclaw plugins install`.
|
||||
|
||||
Npm specs are **registry-only** (package name + optional **exact version** or
|
||||
**dist-tag**). Git/URL/file specs and semver ranges are rejected. Dependency
|
||||
installs run with `--ignore-scripts` for safety.
|
||||
|
||||
Bare specs and `@latest` stay on the stable track. If npm resolves either of
|
||||
those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a
|
||||
prerelease tag such as `@beta`/`@rc` or an exact prerelease version.
|
||||
|
||||
**What it does:**
|
||||
|
||||
- Copies the hook pack into `~/.openclaw/hooks/<id>`
|
||||
- Enables the installed hooks in `hooks.internal.entries.*`
|
||||
- Records the install under `hooks.internal.installs`
|
||||
|
||||
**Options:**
|
||||
|
||||
- `-l, --link`: Link a local directory instead of copying (adds it to `hooks.internal.load.extraDirs`)
|
||||
- `--pin`: Record npm installs as exact resolved `name@version` in `hooks.internal.installs`
|
||||
|
||||
**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Local directory
|
||||
openclaw plugins install ./my-hook-pack
|
||||
|
||||
# Local archive
|
||||
openclaw plugins install ./my-hook-pack.zip
|
||||
|
||||
# NPM package
|
||||
openclaw plugins install @openclaw/my-hook-pack
|
||||
|
||||
# Link a local directory without copying
|
||||
openclaw plugins install -l ./my-hook-pack
|
||||
```
|
||||
|
||||
Linked hook packs are treated as managed hooks from an operator-configured
|
||||
directory, not as workspace hooks.
|
||||
|
||||
## Update Hook Packs
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id>
|
||||
openclaw plugins update --all
|
||||
```
|
||||
|
||||
Update tracked npm-based hook packs through the unified plugins updater.
|
||||
|
||||
`openclaw hooks update` still works as a compatibility alias, but it prints a
|
||||
deprecation warning and forwards to `openclaw plugins update`.
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--all`: Update all tracked hook packs
|
||||
- `--dry-run`: Show what would change without writing
|
||||
|
||||
When a stored integrity hash exists and the fetched artifact hash changes,
|
||||
OpenClaw prints a warning and asks for confirmation before proceeding. Use
|
||||
global `--yes` to bypass prompts in CI/non-interactive runs.
|
||||
|
||||
## Bundled Hooks
|
||||
|
||||
### session-memory
|
||||
|
||||
Saves session context to memory when you issue `/new` or `/reset`.
|
||||
|
||||
**Enable:**
|
||||
|
||||
```bash
|
||||
openclaw hooks enable session-memory
|
||||
```
|
||||
|
||||
**Output:** `~/.openclaw/workspace/memory/YYYY-MM-DD-slug.md`
|
||||
|
||||
**See:** [session-memory documentation](/automation/hooks#session-memory)
|
||||
|
||||
### bootstrap-extra-files
|
||||
|
||||
Injects additional bootstrap files (for example monorepo-local `AGENTS.md` / `TOOLS.md`) during `agent:bootstrap`.
|
||||
|
||||
**Enable:**
|
||||
|
||||
```bash
|
||||
openclaw hooks enable bootstrap-extra-files
|
||||
```
|
||||
|
||||
**See:** [bootstrap-extra-files documentation](/automation/hooks#bootstrap-extra-files)
|
||||
|
||||
### command-logger
|
||||
|
||||
Logs all command events to a centralized audit file.
|
||||
|
||||
**Enable:**
|
||||
|
||||
```bash
|
||||
openclaw hooks enable command-logger
|
||||
```
|
||||
|
||||
**Output:** `~/.openclaw/logs/commands.log`
|
||||
|
||||
**View logs:**
|
||||
|
||||
```bash
|
||||
# Recent commands
|
||||
tail -n 20 ~/.openclaw/logs/commands.log
|
||||
|
||||
# Pretty-print
|
||||
cat ~/.openclaw/logs/commands.log | jq .
|
||||
|
||||
# Filter by action
|
||||
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .
|
||||
```
|
||||
|
||||
**See:** [command-logger documentation](/automation/hooks#command-logger)
|
||||
|
||||
### boot-md
|
||||
|
||||
Runs `BOOT.md` when the gateway starts (after channels start).
|
||||
|
||||
**Events**: `gateway:startup`
|
||||
|
||||
**Enable**:
|
||||
|
||||
```bash
|
||||
openclaw hooks enable boot-md
|
||||
```
|
||||
|
||||
**See:** [boot-md documentation](/automation/hooks#boot-md)
|
||||
1844
openclaw/docs/cli/index.md
Normal file
1844
openclaw/docs/cli/index.md
Normal file
File diff suppressed because it is too large
Load diff
280
openclaw/docs/cli/infer.md
Normal file
280
openclaw/docs/cli/infer.md
Normal file
|
|
@ -0,0 +1,280 @@
|
|||
---
|
||||
summary: "Infer-first CLI for provider-backed model, image, audio, TTS, video, web, and embedding workflows"
|
||||
read_when:
|
||||
- Adding or modifying `openclaw infer` commands
|
||||
- Designing stable headless capability automation
|
||||
title: "Inference CLI"
|
||||
---
|
||||
|
||||
# Inference CLI
|
||||
|
||||
`openclaw infer` is the canonical headless surface for provider-backed inference workflows.
|
||||
|
||||
It intentionally exposes capability families, not raw gateway RPC names and not raw agent tool ids.
|
||||
|
||||
## Turn infer into a skill
|
||||
|
||||
Copy and paste this to an agent:
|
||||
|
||||
```text
|
||||
Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
|
||||
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
|
||||
```
|
||||
|
||||
A good infer-based skill should:
|
||||
|
||||
- map common user intents to the correct infer subcommand
|
||||
- include a few canonical infer examples for the workflows it covers
|
||||
- prefer `openclaw infer ...` in examples and suggestions
|
||||
- avoid re-documenting the entire infer surface inside the skill body
|
||||
|
||||
Typical infer-focused skill coverage:
|
||||
|
||||
- `openclaw infer model run`
|
||||
- `openclaw infer image generate`
|
||||
- `openclaw infer audio transcribe`
|
||||
- `openclaw infer tts convert`
|
||||
- `openclaw infer web search`
|
||||
- `openclaw infer embedding create`
|
||||
|
||||
## Why use infer
|
||||
|
||||
`openclaw infer` provides one consistent CLI for provider-backed inference tasks inside OpenClaw.
|
||||
|
||||
Benefits:
|
||||
|
||||
- Use the providers and models already configured in OpenClaw instead of wiring up one-off wrappers for each backend.
|
||||
- Keep model, image, audio transcription, TTS, video, web, and embedding workflows under one command tree.
|
||||
- Use a stable `--json` output shape for scripts, automation, and agent-driven workflows.
|
||||
- Prefer a first-party OpenClaw surface when the task is fundamentally "run inference."
|
||||
- Use the normal local path without requiring the gateway for most infer commands.
|
||||
|
||||
## Command tree
|
||||
|
||||
```text
|
||||
openclaw infer
|
||||
list
|
||||
inspect
|
||||
|
||||
model
|
||||
run
|
||||
list
|
||||
inspect
|
||||
providers
|
||||
auth login
|
||||
auth logout
|
||||
auth status
|
||||
|
||||
image
|
||||
generate
|
||||
edit
|
||||
describe
|
||||
describe-many
|
||||
providers
|
||||
|
||||
audio
|
||||
transcribe
|
||||
providers
|
||||
|
||||
tts
|
||||
convert
|
||||
voices
|
||||
providers
|
||||
status
|
||||
enable
|
||||
disable
|
||||
set-provider
|
||||
|
||||
video
|
||||
generate
|
||||
describe
|
||||
providers
|
||||
|
||||
web
|
||||
search
|
||||
fetch
|
||||
providers
|
||||
|
||||
embedding
|
||||
create
|
||||
providers
|
||||
```
|
||||
|
||||
## Common tasks
|
||||
|
||||
This table maps common inference tasks to the corresponding infer command.
|
||||
|
||||
| Task | Command | Notes |
|
||||
| ----------------------- | ---------------------------------------------------------------------- | ---------------------------------------------------- |
|
||||
| Run a text/model prompt | `openclaw infer model run --prompt "..." --json` | Uses the normal local path by default |
|
||||
| Generate an image | `openclaw infer image generate --prompt "..." --json` | Use `image edit` when starting from an existing file |
|
||||
| Describe an image file | `openclaw infer image describe --file ./image.png --json` | `--model` must be `<provider/model>` |
|
||||
| Transcribe audio | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` must be `<provider/model>` |
|
||||
| Synthesize speech | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` is gateway-oriented |
|
||||
| Generate a video | `openclaw infer video generate --prompt "..." --json` | |
|
||||
| Describe a video file | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` must be `<provider/model>` |
|
||||
| Search the web | `openclaw infer web search --query "..." --json` | |
|
||||
| Fetch a web page | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| Create embeddings | `openclaw infer embedding create --text "..." --json` | |
|
||||
|
||||
## Behavior
|
||||
|
||||
- `openclaw infer ...` is the primary CLI surface for these workflows.
|
||||
- Use `--json` when the output will be consumed by another command or script.
|
||||
- Use `--provider` or `--model provider/model` when a specific backend is required.
|
||||
- For `image describe`, `audio transcribe`, and `video describe`, `--model` must use the form `<provider/model>`.
|
||||
- Stateless execution commands default to local.
|
||||
- Gateway-managed state commands default to gateway.
|
||||
- The normal local path does not require the gateway to be running.
|
||||
|
||||
## Model
|
||||
|
||||
Use `model` for provider-backed text inference and model/provider inspection.
|
||||
|
||||
```bash
|
||||
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
|
||||
openclaw infer model run --prompt "Summarize this changelog entry" --provider openai --json
|
||||
openclaw infer model providers --json
|
||||
openclaw infer model inspect --name gpt-5.4 --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `model run` reuses the agent runtime so provider/model overrides behave like normal agent execution.
|
||||
- `model auth login`, `model auth logout`, and `model auth status` manage saved provider auth state.
|
||||
|
||||
## Image
|
||||
|
||||
Use `image` for generation, edit, and description.
|
||||
|
||||
```bash
|
||||
openclaw infer image generate --prompt "friendly lobster illustration" --json
|
||||
openclaw infer image generate --prompt "cinematic product photo of headphones" --json
|
||||
openclaw infer image describe --file ./photo.jpg --json
|
||||
openclaw infer image describe --file ./ui-screenshot.png --model openai/gpt-4.1-mini --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Use `image edit` when starting from existing input files.
|
||||
- For `image describe`, `--model` must be `<provider/model>`.
|
||||
|
||||
## Audio
|
||||
|
||||
Use `audio` for file transcription.
|
||||
|
||||
```bash
|
||||
openclaw infer audio transcribe --file ./memo.m4a --json
|
||||
openclaw infer audio transcribe --file ./team-sync.m4a --language en --prompt "Focus on names and action items" --json
|
||||
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `audio transcribe` is for file transcription, not realtime session management.
|
||||
- `--model` must be `<provider/model>`.
|
||||
|
||||
## TTS
|
||||
|
||||
Use `tts` for speech synthesis and TTS provider state.
|
||||
|
||||
```bash
|
||||
openclaw infer tts convert --text "hello from openclaw" --output ./hello.mp3 --json
|
||||
openclaw infer tts convert --text "Your build is complete" --output ./build-complete.mp3 --json
|
||||
openclaw infer tts providers --json
|
||||
openclaw infer tts status --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `tts status` defaults to gateway because it reflects gateway-managed TTS state.
|
||||
- Use `tts providers`, `tts voices`, and `tts set-provider` to inspect and configure TTS behavior.
|
||||
|
||||
## Video
|
||||
|
||||
Use `video` for generation and description.
|
||||
|
||||
```bash
|
||||
openclaw infer video generate --prompt "cinematic sunset over the ocean" --json
|
||||
openclaw infer video generate --prompt "slow drone shot over a forest lake" --json
|
||||
openclaw infer video describe --file ./clip.mp4 --json
|
||||
openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `--model` must be `<provider/model>` for `video describe`.
|
||||
|
||||
## Web
|
||||
|
||||
Use `web` for search and fetch workflows.
|
||||
|
||||
```bash
|
||||
openclaw infer web search --query "OpenClaw docs" --json
|
||||
openclaw infer web search --query "OpenClaw infer web providers" --json
|
||||
openclaw infer web fetch --url https://docs.openclaw.ai/cli/infer --json
|
||||
openclaw infer web providers --json
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Use `web providers` to inspect available, configured, and selected providers.
|
||||
|
||||
## Embedding
|
||||
|
||||
Use `embedding` for vector creation and embedding provider inspection.
|
||||
|
||||
```bash
|
||||
openclaw infer embedding create --text "friendly lobster" --json
|
||||
openclaw infer embedding create --text "customer support ticket: delayed shipment" --model openai/text-embedding-3-large --json
|
||||
openclaw infer embedding providers --json
|
||||
```
|
||||
|
||||
## JSON output
|
||||
|
||||
Infer commands normalize JSON output under a shared envelope:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"capability": "image.generate",
|
||||
"transport": "local",
|
||||
"provider": "openai",
|
||||
"model": "gpt-image-1",
|
||||
"attempts": [],
|
||||
"outputs": []
|
||||
}
|
||||
```
|
||||
|
||||
Top-level fields are stable:
|
||||
|
||||
- `ok`
|
||||
- `capability`
|
||||
- `transport`
|
||||
- `provider`
|
||||
- `model`
|
||||
- `attempts`
|
||||
- `outputs`
|
||||
- `error`
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
```bash
|
||||
# Bad
|
||||
openclaw infer media image generate --prompt "friendly lobster"
|
||||
|
||||
# Good
|
||||
openclaw infer image generate --prompt "friendly lobster"
|
||||
```
|
||||
|
||||
```bash
|
||||
# Bad
|
||||
openclaw infer audio transcribe --file ./memo.m4a --model whisper-1 --json
|
||||
|
||||
# Good
|
||||
openclaw infer audio transcribe --file ./memo.m4a --model openai/whisper-1 --json
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- `openclaw capability ...` is an alias for `openclaw infer ...`.
|
||||
59
openclaw/docs/cli/logs.md
Normal file
59
openclaw/docs/cli/logs.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw logs` (tail gateway logs via RPC)"
|
||||
read_when:
|
||||
- You need to tail Gateway logs remotely (without SSH)
|
||||
- You want JSON log lines for tooling
|
||||
title: "logs"
|
||||
---
|
||||
|
||||
# `openclaw logs`
|
||||
|
||||
Tail Gateway file logs over RPC (works in remote mode).
|
||||
|
||||
Related:
|
||||
|
||||
- Logging overview: [Logging](/logging)
|
||||
- Gateway CLI: [gateway](/cli/gateway)
|
||||
|
||||
## Options
|
||||
|
||||
- `--limit <n>`: maximum number of log lines to return (default `200`)
|
||||
- `--max-bytes <n>`: maximum bytes to read from the log file (default `250000`)
|
||||
- `--follow`: follow the log stream
|
||||
- `--interval <ms>`: polling interval while following (default `1000`)
|
||||
- `--json`: emit line-delimited JSON events
|
||||
- `--plain`: plain text output without styled formatting
|
||||
- `--no-color`: disable ANSI colors
|
||||
- `--local-time`: render timestamps in your local timezone
|
||||
|
||||
## Shared Gateway RPC options
|
||||
|
||||
`openclaw logs` also accepts the standard Gateway client flags:
|
||||
|
||||
- `--url <url>`: Gateway WebSocket URL
|
||||
- `--token <token>`: Gateway token
|
||||
- `--timeout <ms>`: timeout in ms (default `30000`)
|
||||
- `--expect-final`: wait for a final response when the Gateway call is agent-backed
|
||||
|
||||
When you pass `--url`, the CLI does not auto-apply config or environment credentials. Include `--token` explicitly if the target Gateway requires auth.
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw logs
|
||||
openclaw logs --follow
|
||||
openclaw logs --follow --interval 2000
|
||||
openclaw logs --limit 500 --max-bytes 500000
|
||||
openclaw logs --json
|
||||
openclaw logs --plain
|
||||
openclaw logs --no-color
|
||||
openclaw logs --limit 500
|
||||
openclaw logs --local-time
|
||||
openclaw logs --follow --local-time
|
||||
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
|
||||
```
|
||||
|
||||
## Notes
|
||||
|
||||
- Use `--local-time` to render timestamps in your local timezone.
|
||||
- If the local loopback Gateway asks for pairing, `openclaw logs` falls back to the configured local log file automatically. Explicit `--url` targets do not use this fallback.
|
||||
505
openclaw/docs/cli/mcp.md
Normal file
505
openclaw/docs/cli/mcp.md
Normal file
|
|
@ -0,0 +1,505 @@
|
|||
---
|
||||
summary: "Expose OpenClaw channel conversations over MCP and manage saved MCP server definitions"
|
||||
read_when:
|
||||
- Connecting Codex, Claude Code, or another MCP client to OpenClaw-backed channels
|
||||
- Running `openclaw mcp serve`
|
||||
- Managing OpenClaw-saved MCP server definitions
|
||||
title: "mcp"
|
||||
---
|
||||
|
||||
# mcp
|
||||
|
||||
`openclaw mcp` has two jobs:
|
||||
|
||||
- run OpenClaw as an MCP server with `openclaw mcp serve`
|
||||
- manage OpenClaw-owned outbound MCP server definitions with `list`, `show`,
|
||||
`set`, and `unset`
|
||||
|
||||
In other words:
|
||||
|
||||
- `serve` is OpenClaw acting as an MCP server
|
||||
- `list` / `show` / `set` / `unset` is OpenClaw acting as an MCP client-side
|
||||
registry for other MCP servers its runtimes may consume later
|
||||
|
||||
Use [`openclaw acp`](/cli/acp) when OpenClaw should host a coding harness
|
||||
session itself and route that runtime through ACP.
|
||||
|
||||
## OpenClaw as an MCP server
|
||||
|
||||
This is the `openclaw mcp serve` path.
|
||||
|
||||
## When to use `serve`
|
||||
|
||||
Use `openclaw mcp serve` when:
|
||||
|
||||
- Codex, Claude Code, or another MCP client should talk directly to
|
||||
OpenClaw-backed channel conversations
|
||||
- you already have a local or remote OpenClaw Gateway with routed sessions
|
||||
- you want one MCP server that works across OpenClaw's channel backends instead
|
||||
of running separate per-channel bridges
|
||||
|
||||
Use [`openclaw acp`](/cli/acp) instead when OpenClaw should host the coding
|
||||
runtime itself and keep the agent session inside OpenClaw.
|
||||
|
||||
## How it works
|
||||
|
||||
`openclaw mcp serve` starts a stdio MCP server. The MCP client owns that
|
||||
process. While the client keeps the stdio session open, the bridge connects to a
|
||||
local or remote OpenClaw Gateway over WebSocket and exposes routed channel
|
||||
conversations over MCP.
|
||||
|
||||
Lifecycle:
|
||||
|
||||
1. the MCP client spawns `openclaw mcp serve`
|
||||
2. the bridge connects to Gateway
|
||||
3. routed sessions become MCP conversations and transcript/history tools
|
||||
4. live events are queued in memory while the bridge is connected
|
||||
5. if Claude channel mode is enabled, the same session can also receive
|
||||
Claude-specific push notifications
|
||||
|
||||
Important behavior:
|
||||
|
||||
- live queue state starts when the bridge connects
|
||||
- older transcript history is read with `messages_read`
|
||||
- Claude push notifications only exist while the MCP session is alive
|
||||
- when the client disconnects, the bridge exits and the live queue is gone
|
||||
|
||||
## Choose a client mode
|
||||
|
||||
Use the same bridge in two different ways:
|
||||
|
||||
- Generic MCP clients: standard MCP tools only. Use `conversations_list`,
|
||||
`messages_read`, `events_poll`, `events_wait`, `messages_send`, and the
|
||||
approval tools.
|
||||
- Claude Code: standard MCP tools plus the Claude-specific channel adapter.
|
||||
Enable `--claude-channel-mode on` or leave the default `auto`.
|
||||
|
||||
Today, `auto` behaves the same as `on`. There is no client capability detection
|
||||
yet.
|
||||
|
||||
## What `serve` exposes
|
||||
|
||||
The bridge uses existing Gateway session route metadata to expose channel-backed
|
||||
conversations. A conversation appears when OpenClaw already has session state
|
||||
with a known route such as:
|
||||
|
||||
- `channel`
|
||||
- recipient or destination metadata
|
||||
- optional `accountId`
|
||||
- optional `threadId`
|
||||
|
||||
This gives MCP clients one place to:
|
||||
|
||||
- list recent routed conversations
|
||||
- read recent transcript history
|
||||
- wait for new inbound events
|
||||
- send a reply back through the same route
|
||||
- see approval requests that arrive while the bridge is connected
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Local Gateway
|
||||
openclaw mcp serve
|
||||
|
||||
# Remote Gateway
|
||||
openclaw mcp serve --url wss://gateway-host:18789 --token-file ~/.openclaw/gateway.token
|
||||
|
||||
# Remote Gateway with password auth
|
||||
openclaw mcp serve --url wss://gateway-host:18789 --password-file ~/.openclaw/gateway.password
|
||||
|
||||
# Enable verbose bridge logs
|
||||
openclaw mcp serve --verbose
|
||||
|
||||
# Disable Claude-specific push notifications
|
||||
openclaw mcp serve --claude-channel-mode off
|
||||
```
|
||||
|
||||
## Bridge tools
|
||||
|
||||
The current bridge exposes these MCP tools:
|
||||
|
||||
- `conversations_list`
|
||||
- `conversation_get`
|
||||
- `messages_read`
|
||||
- `attachments_fetch`
|
||||
- `events_poll`
|
||||
- `events_wait`
|
||||
- `messages_send`
|
||||
- `permissions_list_open`
|
||||
- `permissions_respond`
|
||||
|
||||
### `conversations_list`
|
||||
|
||||
Lists recent session-backed conversations that already have route metadata in
|
||||
Gateway session state.
|
||||
|
||||
Useful filters:
|
||||
|
||||
- `limit`
|
||||
- `search`
|
||||
- `channel`
|
||||
- `includeDerivedTitles`
|
||||
- `includeLastMessage`
|
||||
|
||||
### `conversation_get`
|
||||
|
||||
Returns one conversation by `session_key`.
|
||||
|
||||
### `messages_read`
|
||||
|
||||
Reads recent transcript messages for one session-backed conversation.
|
||||
|
||||
### `attachments_fetch`
|
||||
|
||||
Extracts non-text message content blocks from one transcript message. This is a
|
||||
metadata view over transcript content, not a standalone durable attachment blob
|
||||
store.
|
||||
|
||||
### `events_poll`
|
||||
|
||||
Reads queued live events since a numeric cursor.
|
||||
|
||||
### `events_wait`
|
||||
|
||||
Long-polls until the next matching queued event arrives or a timeout expires.
|
||||
|
||||
Use this when a generic MCP client needs near-real-time delivery without a
|
||||
Claude-specific push protocol.
|
||||
|
||||
### `messages_send`
|
||||
|
||||
Sends text back through the same route already recorded on the session.
|
||||
|
||||
Current behavior:
|
||||
|
||||
- requires an existing conversation route
|
||||
- uses the session's channel, recipient, account id, and thread id
|
||||
- sends text only
|
||||
|
||||
### `permissions_list_open`
|
||||
|
||||
Lists pending exec/plugin approval requests the bridge has observed since it
|
||||
connected to the Gateway.
|
||||
|
||||
### `permissions_respond`
|
||||
|
||||
Resolves one pending exec/plugin approval request with:
|
||||
|
||||
- `allow-once`
|
||||
- `allow-always`
|
||||
- `deny`
|
||||
|
||||
## Event model
|
||||
|
||||
The bridge keeps an in-memory event queue while it is connected.
|
||||
|
||||
Current event types:
|
||||
|
||||
- `message`
|
||||
- `exec_approval_requested`
|
||||
- `exec_approval_resolved`
|
||||
- `plugin_approval_requested`
|
||||
- `plugin_approval_resolved`
|
||||
- `claude_permission_request`
|
||||
|
||||
Important limits:
|
||||
|
||||
- the queue is live-only; it starts when the MCP bridge starts
|
||||
- `events_poll` and `events_wait` do not replay older Gateway history by
|
||||
themselves
|
||||
- durable backlog should be read with `messages_read`
|
||||
|
||||
## Claude channel notifications
|
||||
|
||||
The bridge can also expose Claude-specific channel notifications. This is the
|
||||
OpenClaw equivalent of a Claude Code channel adapter: standard MCP tools remain
|
||||
available, but live inbound messages can also arrive as Claude-specific MCP
|
||||
notifications.
|
||||
|
||||
Flags:
|
||||
|
||||
- `--claude-channel-mode off`: standard MCP tools only
|
||||
- `--claude-channel-mode on`: enable Claude channel notifications
|
||||
- `--claude-channel-mode auto`: current default; same bridge behavior as `on`
|
||||
|
||||
When Claude channel mode is enabled, the server advertises Claude experimental
|
||||
capabilities and can emit:
|
||||
|
||||
- `notifications/claude/channel`
|
||||
- `notifications/claude/channel/permission`
|
||||
|
||||
Current bridge behavior:
|
||||
|
||||
- inbound `user` transcript messages are forwarded as
|
||||
`notifications/claude/channel`
|
||||
- Claude permission requests received over MCP are tracked in-memory
|
||||
- if the linked conversation later sends `yes abcde` or `no abcde`, the bridge
|
||||
converts that to `notifications/claude/channel/permission`
|
||||
- these notifications are live-session only; if the MCP client disconnects,
|
||||
there is no push target
|
||||
|
||||
This is intentionally client-specific. Generic MCP clients should rely on the
|
||||
standard polling tools.
|
||||
|
||||
## MCP client config
|
||||
|
||||
Example stdio client config:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"openclaw": {
|
||||
"command": "openclaw",
|
||||
"args": [
|
||||
"mcp",
|
||||
"serve",
|
||||
"--url",
|
||||
"wss://gateway-host:18789",
|
||||
"--token-file",
|
||||
"/path/to/gateway.token"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
For most generic MCP clients, start with the standard tool surface and ignore
|
||||
Claude mode. Turn Claude mode on only for clients that actually understand the
|
||||
Claude-specific notification methods.
|
||||
|
||||
## Options
|
||||
|
||||
`openclaw mcp serve` supports:
|
||||
|
||||
- `--url <url>`: Gateway WebSocket URL
|
||||
- `--token <token>`: Gateway token
|
||||
- `--token-file <path>`: read token from file
|
||||
- `--password <password>`: Gateway password
|
||||
- `--password-file <path>`: read password from file
|
||||
- `--claude-channel-mode <auto|on|off>`: Claude notification mode
|
||||
- `-v`, `--verbose`: verbose logs on stderr
|
||||
|
||||
Prefer `--token-file` or `--password-file` over inline secrets when possible.
|
||||
|
||||
## Security and trust boundary
|
||||
|
||||
The bridge does not invent routing. It only exposes conversations that Gateway
|
||||
already knows how to route.
|
||||
|
||||
That means:
|
||||
|
||||
- sender allowlists, pairing, and channel-level trust still belong to the
|
||||
underlying OpenClaw channel configuration
|
||||
- `messages_send` can only reply through an existing stored route
|
||||
- approval state is live/in-memory only for the current bridge session
|
||||
- bridge auth should use the same Gateway token or password controls you would
|
||||
trust for any other remote Gateway client
|
||||
|
||||
If a conversation is missing from `conversations_list`, the usual cause is not
|
||||
MCP configuration. It is missing or incomplete route metadata in the underlying
|
||||
Gateway session.
|
||||
|
||||
## Testing
|
||||
|
||||
OpenClaw ships a deterministic Docker smoke for this bridge:
|
||||
|
||||
```bash
|
||||
pnpm test:docker:mcp-channels
|
||||
```
|
||||
|
||||
That smoke:
|
||||
|
||||
- starts a seeded Gateway container
|
||||
- starts a second container that spawns `openclaw mcp serve`
|
||||
- verifies conversation discovery, transcript reads, attachment metadata reads,
|
||||
live event queue behavior, and outbound send routing
|
||||
- validates Claude-style channel and permission notifications over the real
|
||||
stdio MCP bridge
|
||||
|
||||
This is the fastest way to prove the bridge works without wiring a real
|
||||
Telegram, Discord, or iMessage account into the test run.
|
||||
|
||||
For broader testing context, see [Testing](/help/testing).
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### No conversations returned
|
||||
|
||||
Usually means the Gateway session is not already routable. Confirm that the
|
||||
underlying session has stored channel/provider, recipient, and optional
|
||||
account/thread route metadata.
|
||||
|
||||
### `events_poll` or `events_wait` misses older messages
|
||||
|
||||
Expected. The live queue starts when the bridge connects. Read older transcript
|
||||
history with `messages_read`.
|
||||
|
||||
### Claude notifications do not show up
|
||||
|
||||
Check all of these:
|
||||
|
||||
- the client kept the stdio MCP session open
|
||||
- `--claude-channel-mode` is `on` or `auto`
|
||||
- the client actually understands the Claude-specific notification methods
|
||||
- the inbound message happened after the bridge connected
|
||||
|
||||
### Approvals are missing
|
||||
|
||||
`permissions_list_open` only shows approval requests observed while the bridge
|
||||
was connected. It is not a durable approval history API.
|
||||
|
||||
## OpenClaw as an MCP client registry
|
||||
|
||||
This is the `openclaw mcp list`, `show`, `set`, and `unset` path.
|
||||
|
||||
These commands do not expose OpenClaw over MCP. They manage OpenClaw-owned MCP
|
||||
server definitions under `mcp.servers` in OpenClaw config.
|
||||
|
||||
Those saved definitions are for runtimes that OpenClaw launches or configures
|
||||
later, such as embedded Pi and other runtime adapters. OpenClaw stores the
|
||||
definitions centrally so those runtimes do not need to keep their own duplicate
|
||||
MCP server lists.
|
||||
|
||||
Important behavior:
|
||||
|
||||
- these commands only read or write OpenClaw config
|
||||
- they do not connect to the target MCP server
|
||||
- they do not validate whether the command, URL, or remote transport is
|
||||
reachable right now
|
||||
- runtime adapters decide which transport shapes they actually support at
|
||||
execution time
|
||||
|
||||
## Saved MCP server definitions
|
||||
|
||||
OpenClaw also stores a lightweight MCP server registry in config for surfaces
|
||||
that want OpenClaw-managed MCP definitions.
|
||||
|
||||
Commands:
|
||||
|
||||
- `openclaw mcp list`
|
||||
- `openclaw mcp show [name]`
|
||||
- `openclaw mcp set <name> <json>`
|
||||
- `openclaw mcp unset <name>`
|
||||
|
||||
Notes:
|
||||
|
||||
- `list` sorts server names.
|
||||
- `show` without a name prints the full configured MCP server object.
|
||||
- `set` expects one JSON object value on the command line.
|
||||
- `unset` fails if the named server does not exist.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw mcp list
|
||||
openclaw mcp show context7 --json
|
||||
openclaw mcp set context7 '{"command":"uvx","args":["context7-mcp"]}'
|
||||
openclaw mcp set docs '{"url":"https://mcp.example.com"}'
|
||||
openclaw mcp unset context7
|
||||
```
|
||||
|
||||
Example config shape:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"context7": {
|
||||
"command": "uvx",
|
||||
"args": ["context7-mcp"]
|
||||
},
|
||||
"docs": {
|
||||
"url": "https://mcp.example.com"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Stdio transport
|
||||
|
||||
Launches a local child process and communicates over stdin/stdout.
|
||||
|
||||
| Field | Description |
|
||||
| -------------------------- | --------------------------------- |
|
||||
| `command` | Executable to spawn (required) |
|
||||
| `args` | Array of command-line arguments |
|
||||
| `env` | Extra environment variables |
|
||||
| `cwd` / `workingDirectory` | Working directory for the process |
|
||||
|
||||
### SSE / HTTP transport
|
||||
|
||||
Connects to a remote MCP server over HTTP Server-Sent Events.
|
||||
|
||||
| Field | Description |
|
||||
| --------------------- | ---------------------------------------------------------------- |
|
||||
| `url` | HTTP or HTTPS URL of the remote server (required) |
|
||||
| `headers` | Optional key-value map of HTTP headers (for example auth tokens) |
|
||||
| `connectionTimeoutMs` | Per-server connection timeout in ms (optional) |
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"remote-tools": {
|
||||
"url": "https://mcp.example.com",
|
||||
"headers": {
|
||||
"Authorization": "Bearer <token>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Sensitive values in `url` (userinfo) and `headers` are redacted in logs and
|
||||
status output.
|
||||
|
||||
### Streamable HTTP transport
|
||||
|
||||
`streamable-http` is an additional transport option alongside `sse` and `stdio`. It uses HTTP streaming for bidirectional communication with remote MCP servers.
|
||||
|
||||
| Field | Description |
|
||||
| --------------------- | -------------------------------------------------------------------------------------- |
|
||||
| `url` | HTTP or HTTPS URL of the remote server (required) |
|
||||
| `transport` | Set to `"streamable-http"` to select this transport; when omitted, OpenClaw uses `sse` |
|
||||
| `headers` | Optional key-value map of HTTP headers (for example auth tokens) |
|
||||
| `connectionTimeoutMs` | Per-server connection timeout in ms (optional) |
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcp": {
|
||||
"servers": {
|
||||
"streaming-tools": {
|
||||
"url": "https://mcp.example.com/stream",
|
||||
"transport": "streamable-http",
|
||||
"connectionTimeoutMs": 10000,
|
||||
"headers": {
|
||||
"Authorization": "Bearer <token>"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
These commands manage saved config only. They do not start the channel bridge,
|
||||
open a live MCP client session, or prove the target server is reachable.
|
||||
|
||||
## Current limits
|
||||
|
||||
This page documents the bridge as shipped today.
|
||||
|
||||
Current limits:
|
||||
|
||||
- conversation discovery depends on existing Gateway session route metadata
|
||||
- no generic push protocol beyond the Claude-specific adapter
|
||||
- no message edit or react tools yet
|
||||
- HTTP/SSE/streamable-http transport connects to a single remote server; no multiplexed upstream yet
|
||||
- `permissions_list_open` only includes approvals observed while the bridge is
|
||||
connected
|
||||
174
openclaw/docs/cli/memory.md
Normal file
174
openclaw/docs/cli/memory.md
Normal file
|
|
@ -0,0 +1,174 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw memory` (status/index/search/promote/promote-explain/rem-harness)"
|
||||
read_when:
|
||||
- You want to index or search semantic memory
|
||||
- You’re debugging memory availability or indexing
|
||||
- You want to promote recalled short-term memory into `MEMORY.md`
|
||||
title: "memory"
|
||||
---
|
||||
|
||||
# `openclaw memory`
|
||||
|
||||
Manage semantic memory indexing and search.
|
||||
Provided by the active memory plugin (default: `memory-core`; set `plugins.slots.memory = "none"` to disable).
|
||||
|
||||
Related:
|
||||
|
||||
- Memory concept: [Memory](/concepts/memory)
|
||||
- Memory wiki: [Memory Wiki](/plugins/memory-wiki)
|
||||
- Wiki CLI: [wiki](/cli/wiki)
|
||||
- Plugins: [Plugins](/tools/plugin)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw memory status
|
||||
openclaw memory status --deep
|
||||
openclaw memory status --fix
|
||||
openclaw memory index --force
|
||||
openclaw memory search "meeting notes"
|
||||
openclaw memory search --query "deployment" --max-results 20
|
||||
openclaw memory promote --limit 10 --min-score 0.75
|
||||
openclaw memory promote --apply
|
||||
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
|
||||
openclaw memory promote-explain "router vlan"
|
||||
openclaw memory promote-explain "router vlan" --json
|
||||
openclaw memory rem-harness
|
||||
openclaw memory rem-harness --json
|
||||
openclaw memory status --json
|
||||
openclaw memory status --deep --index
|
||||
openclaw memory status --deep --index --verbose
|
||||
openclaw memory status --agent main
|
||||
openclaw memory index --agent main --verbose
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
`memory status` and `memory index`:
|
||||
|
||||
- `--agent <id>`: scope to a single agent. Without it, these commands run for each configured agent; if no agent list is configured, they fall back to the default agent.
|
||||
- `--verbose`: emit detailed logs during probes and indexing.
|
||||
|
||||
`memory status`:
|
||||
|
||||
- `--deep`: probe vector + embedding availability.
|
||||
- `--index`: run a reindex if the store is dirty (implies `--deep`).
|
||||
- `--fix`: repair stale recall locks and normalize promotion metadata.
|
||||
- `--json`: print JSON output.
|
||||
|
||||
`memory index`:
|
||||
|
||||
- `--force`: force a full reindex.
|
||||
|
||||
`memory search`:
|
||||
|
||||
- Query input: pass either positional `[query]` or `--query <text>`.
|
||||
- If both are provided, `--query` wins.
|
||||
- If neither is provided, the command exits with an error.
|
||||
- `--agent <id>`: scope to a single agent (default: the default agent).
|
||||
- `--max-results <n>`: limit the number of results returned.
|
||||
- `--min-score <n>`: filter out low-score matches.
|
||||
- `--json`: print JSON results.
|
||||
|
||||
`memory promote`:
|
||||
|
||||
Preview and apply short-term memory promotions.
|
||||
|
||||
```bash
|
||||
openclaw memory promote [--apply] [--limit <n>] [--include-promoted]
|
||||
```
|
||||
|
||||
- `--apply` -- write promotions to `MEMORY.md` (default: preview only).
|
||||
- `--limit <n>` -- cap the number of candidates shown.
|
||||
- `--include-promoted` -- include entries already promoted in previous cycles.
|
||||
|
||||
Full options:
|
||||
|
||||
- Ranks short-term candidates from `memory/YYYY-MM-DD.md` using weighted promotion signals (`frequency`, `relevance`, `query diversity`, `recency`, `consolidation`, `conceptual richness`).
|
||||
- Uses short-term signals from both memory recalls and daily-ingestion passes, plus light/REM phase reinforcement signals.
|
||||
- When dreaming is enabled, `memory-core` auto-manages one cron job that runs a full sweep (`light -> REM -> deep`) in the background (no manual `openclaw cron add` required).
|
||||
- `--agent <id>`: scope to a single agent (default: the default agent).
|
||||
- `--limit <n>`: max candidates to return/apply.
|
||||
- `--min-score <n>`: minimum weighted promotion score.
|
||||
- `--min-recall-count <n>`: minimum recall count required for a candidate.
|
||||
- `--min-unique-queries <n>`: minimum distinct query count required for a candidate.
|
||||
- `--apply`: append selected candidates into `MEMORY.md` and mark them promoted.
|
||||
- `--include-promoted`: include already promoted candidates in output.
|
||||
- `--json`: print JSON output.
|
||||
|
||||
`memory promote-explain`:
|
||||
|
||||
Explain a specific promotion candidate and its score breakdown.
|
||||
|
||||
```bash
|
||||
openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]
|
||||
```
|
||||
|
||||
- `<selector>`: candidate key, path fragment, or snippet fragment to look up.
|
||||
- `--agent <id>`: scope to a single agent (default: the default agent).
|
||||
- `--include-promoted`: include already promoted candidates.
|
||||
- `--json`: print JSON output.
|
||||
|
||||
`memory rem-harness`:
|
||||
|
||||
Preview REM reflections, candidate truths, and deep promotion output without writing anything.
|
||||
|
||||
```bash
|
||||
openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]
|
||||
```
|
||||
|
||||
- `--agent <id>`: scope to a single agent (default: the default agent).
|
||||
- `--include-promoted`: include already promoted deep candidates.
|
||||
- `--json`: print JSON output.
|
||||
|
||||
## Dreaming
|
||||
|
||||
Dreaming is the background memory consolidation system with three cooperative
|
||||
phases: **light** (sort/stage short-term material), **deep** (promote durable
|
||||
facts into `MEMORY.md`), and **REM** (reflect and surface themes).
|
||||
|
||||
- Enable with `plugins.entries.memory-core.config.dreaming.enabled: true`.
|
||||
- Toggle from chat with `/dreaming on|off` (or inspect with `/dreaming status`).
|
||||
- Dreaming runs on one managed sweep schedule (`dreaming.frequency`) and executes phases in order: light, REM, deep.
|
||||
- Only the deep phase writes durable memory to `MEMORY.md`.
|
||||
- Human-readable phase output and diary entries are written to `DREAMS.md` (or existing `dreams.md`), with optional per-phase reports in `memory/dreaming/<phase>/YYYY-MM-DD.md`.
|
||||
- Ranking uses weighted signals: recall frequency, retrieval relevance, query diversity, temporal recency, cross-day consolidation, and derived concept richness.
|
||||
- Promotion re-reads the live daily note before writing to `MEMORY.md`, so edited or deleted short-term snippets do not get promoted from stale recall-store snapshots.
|
||||
- Scheduled and manual `memory promote` runs share the same deep phase defaults unless you pass CLI threshold overrides.
|
||||
- Automatic runs fan out across configured memory workspaces.
|
||||
|
||||
Default scheduling:
|
||||
|
||||
- **Sweep cadence**: `dreaming.frequency = 0 3 * * *`
|
||||
- **Deep thresholds**: `minScore=0.8`, `minRecallCount=3`, `minUniqueQueries=3`, `recencyHalfLifeDays=14`, `maxAgeDays=30`
|
||||
|
||||
Example:
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": {
|
||||
"entries": {
|
||||
"memory-core": {
|
||||
"config": {
|
||||
"dreaming": {
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `memory index --verbose` prints per-phase details (provider, model, sources, batch activity).
|
||||
- `memory status` includes any extra paths configured via `memorySearch.extraPaths`.
|
||||
- If effectively active memory remote API key fields are configured as SecretRefs, the command resolves those values from the active gateway snapshot. If gateway is unavailable, the command fails fast.
|
||||
- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
|
||||
- Tune scheduled sweep cadence with `dreaming.frequency`. Deep promotion policy is otherwise internal; use CLI flags on `memory promote` when you need one-off manual overrides.
|
||||
- `memory rem-harness --path <file-or-dir> --grounded` previews grounded `What Happened`, `Reflections`, and `Possible Lasting Updates` from historical daily notes without writing anything.
|
||||
- `memory rem-backfill --path <file-or-dir>` writes reversible grounded diary entries into `DREAMS.md` for UI review.
|
||||
- `memory rem-backfill --path <file-or-dir> --stage-short-term` also seeds grounded durable candidates into the live short-term promotion store so the normal deep phase can rank them.
|
||||
- `memory rem-backfill --rollback` removes previously written grounded diary entries, and `memory rem-backfill --rollback-short-term` removes previously staged grounded short-term candidates.
|
||||
- See [Dreaming](/concepts/dreaming) for full phase descriptions and configuration reference.
|
||||
300
openclaw/docs/cli/message.md
Normal file
300
openclaw/docs/cli/message.md
Normal file
|
|
@ -0,0 +1,300 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw message` (send + channel actions)"
|
||||
read_when:
|
||||
- Adding or modifying message CLI actions
|
||||
- Changing outbound channel behavior
|
||||
title: "message"
|
||||
---
|
||||
|
||||
# `openclaw message`
|
||||
|
||||
Single outbound command for sending messages and channel actions
|
||||
(Discord/Google Chat/iMessage/Matrix/Mattermost (plugin)/Microsoft Teams/Signal/Slack/Telegram/WhatsApp).
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
openclaw message <subcommand> [flags]
|
||||
```
|
||||
|
||||
Channel selection:
|
||||
|
||||
- `--channel` required if more than one channel is configured.
|
||||
- If exactly one channel is configured, it becomes the default.
|
||||
- Values: `discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp` (Mattermost requires plugin)
|
||||
|
||||
Target formats (`--target`):
|
||||
|
||||
- WhatsApp: E.164 or group JID
|
||||
- Telegram: chat id or `@username`
|
||||
- Discord: `channel:<id>` or `user:<id>` (or `<@id>` mention; raw numeric ids are treated as channels)
|
||||
- Google Chat: `spaces/<spaceId>` or `users/<userId>`
|
||||
- Slack: `channel:<id>` or `user:<id>` (raw channel id is accepted)
|
||||
- Mattermost (plugin): `channel:<id>`, `user:<id>`, or `@username` (bare ids are treated as channels)
|
||||
- Signal: `+E.164`, `group:<id>`, `signal:+E.164`, `signal:group:<id>`, or `username:<name>`/`u:<name>`
|
||||
- iMessage: handle, `chat_id:<id>`, `chat_guid:<guid>`, or `chat_identifier:<id>`
|
||||
- Matrix: `@user:server`, `!room:server`, or `#alias:server`
|
||||
- Microsoft Teams: conversation id (`19:...@thread.tacv2`) or `conversation:<id>` or `user:<aad-object-id>`
|
||||
|
||||
Name lookup:
|
||||
|
||||
- For supported providers (Discord/Slack/etc), channel names like `Help` or `#help` are resolved via the directory cache.
|
||||
- On cache miss, OpenClaw will attempt a live directory lookup when the provider supports it.
|
||||
|
||||
## Common flags
|
||||
|
||||
- `--channel <name>`
|
||||
- `--account <id>`
|
||||
- `--target <dest>` (target channel or user for send/poll/read/etc)
|
||||
- `--targets <name>` (repeat; broadcast only)
|
||||
- `--json`
|
||||
- `--dry-run`
|
||||
- `--verbose`
|
||||
|
||||
## SecretRef behavior
|
||||
|
||||
- `openclaw message` resolves supported channel SecretRefs before running the selected action.
|
||||
- Resolution is scoped to the active action target when possible:
|
||||
- channel-scoped when `--channel` is set (or inferred from prefixed targets like `discord:...`)
|
||||
- account-scoped when `--account` is set (channel globals + selected account surfaces)
|
||||
- when `--account` is omitted, OpenClaw does not force a `default` account SecretRef scope
|
||||
- Unresolved SecretRefs on unrelated channels do not block a targeted message action.
|
||||
- If the selected channel/account SecretRef is unresolved, the command fails closed for that action.
|
||||
|
||||
## Actions
|
||||
|
||||
### Core
|
||||
|
||||
- `send`
|
||||
- Channels: WhatsApp/Telegram/Discord/Google Chat/Slack/Mattermost (plugin)/Signal/iMessage/Matrix/Microsoft Teams
|
||||
- Required: `--target`, plus `--message` or `--media`
|
||||
- Optional: `--media`, `--interactive`, `--buttons`, `--components`, `--card`, `--reply-to`, `--thread-id`, `--gif-playback`, `--force-document`, `--silent`
|
||||
- Shared interactive payloads: `--interactive` sends a channel-native interactive JSON payload when supported
|
||||
- Telegram only: `--buttons` (requires `channels.telegram.capabilities.inlineButtons` to allow it)
|
||||
- Telegram only: `--force-document` (send images and GIFs as documents to avoid Telegram compression)
|
||||
- Telegram only: `--thread-id` (forum topic id)
|
||||
- Slack only: `--thread-id` (thread timestamp; `--reply-to` uses the same field)
|
||||
- Discord only: `--components` JSON payload
|
||||
- Adaptive-card channels: `--card` JSON payload when supported
|
||||
- Telegram + Discord: `--silent`
|
||||
- WhatsApp only: `--gif-playback`
|
||||
|
||||
- `poll`
|
||||
- Channels: WhatsApp/Telegram/Discord/Matrix/Microsoft Teams
|
||||
- Required: `--target`, `--poll-question`, `--poll-option` (repeat)
|
||||
- Optional: `--poll-multi`
|
||||
- Discord only: `--poll-duration-hours`, `--silent`, `--message`
|
||||
- Telegram only: `--poll-duration-seconds` (5-600), `--silent`, `--poll-anonymous` / `--poll-public`, `--thread-id`
|
||||
|
||||
- `react`
|
||||
- Channels: Discord/Google Chat/Slack/Telegram/WhatsApp/Signal/Matrix
|
||||
- Required: `--message-id`, `--target`
|
||||
- Optional: `--emoji`, `--remove`, `--participant`, `--from-me`, `--target-author`, `--target-author-uuid`
|
||||
- Note: `--remove` requires `--emoji` (omit `--emoji` to clear own reactions where supported; see /tools/reactions)
|
||||
- WhatsApp only: `--participant`, `--from-me`
|
||||
- Signal group reactions: `--target-author` or `--target-author-uuid` required
|
||||
|
||||
- `reactions`
|
||||
- Channels: Discord/Google Chat/Slack/Matrix
|
||||
- Required: `--message-id`, `--target`
|
||||
- Optional: `--limit`
|
||||
|
||||
- `read`
|
||||
- Channels: Discord/Slack/Matrix
|
||||
- Required: `--target`
|
||||
- Optional: `--limit`, `--before`, `--after`
|
||||
- Discord only: `--around`
|
||||
|
||||
- `edit`
|
||||
- Channels: Discord/Slack/Matrix
|
||||
- Required: `--message-id`, `--message`, `--target`
|
||||
|
||||
- `delete`
|
||||
- Channels: Discord/Slack/Telegram/Matrix
|
||||
- Required: `--message-id`, `--target`
|
||||
|
||||
- `pin` / `unpin`
|
||||
- Channels: Discord/Slack/Matrix
|
||||
- Required: `--message-id`, `--target`
|
||||
|
||||
- `pins` (list)
|
||||
- Channels: Discord/Slack/Matrix
|
||||
- Required: `--target`
|
||||
|
||||
- `permissions`
|
||||
- Channels: Discord/Matrix
|
||||
- Required: `--target`
|
||||
- Matrix only: available when Matrix encryption is enabled and verification actions are allowed
|
||||
|
||||
- `search`
|
||||
- Channels: Discord
|
||||
- Required: `--guild-id`, `--query`
|
||||
- Optional: `--channel-id`, `--channel-ids` (repeat), `--author-id`, `--author-ids` (repeat), `--limit`
|
||||
|
||||
### Threads
|
||||
|
||||
- `thread create`
|
||||
- Channels: Discord
|
||||
- Required: `--thread-name`, `--target` (channel id)
|
||||
- Optional: `--message-id`, `--message`, `--auto-archive-min`
|
||||
|
||||
- `thread list`
|
||||
- Channels: Discord
|
||||
- Required: `--guild-id`
|
||||
- Optional: `--channel-id`, `--include-archived`, `--before`, `--limit`
|
||||
|
||||
- `thread reply`
|
||||
- Channels: Discord
|
||||
- Required: `--target` (thread id), `--message`
|
||||
- Optional: `--media`, `--reply-to`
|
||||
|
||||
### Emojis
|
||||
|
||||
- `emoji list`
|
||||
- Discord: `--guild-id`
|
||||
- Slack: no extra flags
|
||||
|
||||
- `emoji upload`
|
||||
- Channels: Discord
|
||||
- Required: `--guild-id`, `--emoji-name`, `--media`
|
||||
- Optional: `--role-ids` (repeat)
|
||||
|
||||
### Stickers
|
||||
|
||||
- `sticker send`
|
||||
- Channels: Discord
|
||||
- Required: `--target`, `--sticker-id` (repeat)
|
||||
- Optional: `--message`
|
||||
|
||||
- `sticker upload`
|
||||
- Channels: Discord
|
||||
- Required: `--guild-id`, `--sticker-name`, `--sticker-desc`, `--sticker-tags`, `--media`
|
||||
|
||||
### Roles / Channels / Members / Voice
|
||||
|
||||
- `role info` (Discord): `--guild-id`
|
||||
- `role add` / `role remove` (Discord): `--guild-id`, `--user-id`, `--role-id`
|
||||
- `channel info` (Discord): `--target`
|
||||
- `channel list` (Discord): `--guild-id`
|
||||
- `member info` (Discord/Slack): `--user-id` (+ `--guild-id` for Discord)
|
||||
- `voice status` (Discord): `--guild-id`, `--user-id`
|
||||
|
||||
### Events
|
||||
|
||||
- `event list` (Discord): `--guild-id`
|
||||
- `event create` (Discord): `--guild-id`, `--event-name`, `--start-time`
|
||||
- Optional: `--end-time`, `--desc`, `--channel-id`, `--location`, `--event-type`
|
||||
|
||||
### Moderation (Discord)
|
||||
|
||||
- `timeout`: `--guild-id`, `--user-id` (optional `--duration-min` or `--until`; omit both to clear timeout)
|
||||
- `kick`: `--guild-id`, `--user-id` (+ `--reason`)
|
||||
- `ban`: `--guild-id`, `--user-id` (+ `--delete-days`, `--reason`)
|
||||
- `timeout` also supports `--reason`
|
||||
|
||||
### Broadcast
|
||||
|
||||
- `broadcast`
|
||||
- Channels: any configured channel; use `--channel all` to target all providers
|
||||
- Required: `--targets <target...>`
|
||||
- Optional: `--message`, `--media`, `--dry-run`
|
||||
|
||||
## Examples
|
||||
|
||||
Send a Discord reply:
|
||||
|
||||
```
|
||||
openclaw message send --channel discord \
|
||||
--target channel:123 --message "hi" --reply-to 456
|
||||
```
|
||||
|
||||
Send a Discord message with components:
|
||||
|
||||
```
|
||||
openclaw message send --channel discord \
|
||||
--target channel:123 --message "Choose:" \
|
||||
--components '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve","style":"success"},{"label":"Decline","style":"danger"}]}]}'
|
||||
```
|
||||
|
||||
See [Discord components](/channels/discord#interactive-components) for the full schema.
|
||||
|
||||
Send a shared interactive payload:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel googlechat --target spaces/AAA... \
|
||||
--message "Choose:" \
|
||||
--interactive '{"text":"Choose a path","blocks":[{"type":"actions","buttons":[{"label":"Approve"},{"label":"Decline"}]}]}'
|
||||
```
|
||||
|
||||
Create a Discord poll:
|
||||
|
||||
```
|
||||
openclaw message poll --channel discord \
|
||||
--target channel:123 \
|
||||
--poll-question "Snack?" \
|
||||
--poll-option Pizza --poll-option Sushi \
|
||||
--poll-multi --poll-duration-hours 48
|
||||
```
|
||||
|
||||
Create a Telegram poll (auto-close in 2 minutes):
|
||||
|
||||
```
|
||||
openclaw message poll --channel telegram \
|
||||
--target @mychat \
|
||||
--poll-question "Lunch?" \
|
||||
--poll-option Pizza --poll-option Sushi \
|
||||
--poll-duration-seconds 120 --silent
|
||||
```
|
||||
|
||||
Send a Teams proactive message:
|
||||
|
||||
```
|
||||
openclaw message send --channel msteams \
|
||||
--target conversation:19:abc@thread.tacv2 --message "hi"
|
||||
```
|
||||
|
||||
Create a Teams poll:
|
||||
|
||||
```
|
||||
openclaw message poll --channel msteams \
|
||||
--target conversation:19:abc@thread.tacv2 \
|
||||
--poll-question "Lunch?" \
|
||||
--poll-option Pizza --poll-option Sushi
|
||||
```
|
||||
|
||||
React in Slack:
|
||||
|
||||
```
|
||||
openclaw message react --channel slack \
|
||||
--target C123 --message-id 456 --emoji "✅"
|
||||
```
|
||||
|
||||
React in a Signal group:
|
||||
|
||||
```
|
||||
openclaw message react --channel signal \
|
||||
--target signal:group:abc123 --message-id 1737630212345 \
|
||||
--emoji "✅" --target-author-uuid 123e4567-e89b-12d3-a456-426614174000
|
||||
```
|
||||
|
||||
Send Telegram inline buttons:
|
||||
|
||||
```
|
||||
openclaw message send --channel telegram --target @mychat --message "Choose:" \
|
||||
--buttons '[ [{"text":"Yes","callback_data":"cmd:yes"}], [{"text":"No","callback_data":"cmd:no"}] ]'
|
||||
```
|
||||
|
||||
Send a Teams Adaptive Card:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel msteams \
|
||||
--target conversation:19:abc@thread.tacv2 \
|
||||
--card '{"type":"AdaptiveCard","version":"1.5","body":[{"type":"TextBlock","text":"Status update"}]}'
|
||||
```
|
||||
|
||||
Send a Telegram image as a document to avoid compression:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target @mychat \
|
||||
--media ./diagram.png --force-document
|
||||
```
|
||||
134
openclaw/docs/cli/models.md
Normal file
134
openclaw/docs/cli/models.md
Normal file
|
|
@ -0,0 +1,134 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw models` (status/list/set/scan, aliases, fallbacks, auth)"
|
||||
read_when:
|
||||
- You want to change default models or view provider auth status
|
||||
- You want to scan available models/providers and debug auth profiles
|
||||
title: "models"
|
||||
---
|
||||
|
||||
# `openclaw models`
|
||||
|
||||
Model discovery, scanning, and configuration (default model, fallbacks, auth profiles).
|
||||
|
||||
Related:
|
||||
|
||||
- Providers + models: [Models](/providers/models)
|
||||
- Provider auth setup: [Getting started](/start/getting-started)
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw models status
|
||||
openclaw models list
|
||||
openclaw models set <model-or-alias>
|
||||
openclaw models scan
|
||||
```
|
||||
|
||||
`openclaw models status` shows the resolved default/fallbacks plus an auth overview.
|
||||
When provider usage snapshots are available, the OAuth/API-key status section includes
|
||||
provider usage windows and quota snapshots.
|
||||
Current usage-window providers: Anthropic, GitHub Copilot, Gemini CLI, OpenAI
|
||||
Codex, MiniMax, Xiaomi, and z.ai. Usage auth comes from provider-specific hooks
|
||||
when available; otherwise OpenClaw falls back to matching OAuth/API-key
|
||||
credentials from auth profiles, env, or config.
|
||||
In `--json` output, `auth.providers` is the env/config/store-aware provider
|
||||
overview, while `auth.oauth` is auth-store profile health only.
|
||||
Add `--probe` to run live auth probes against each configured provider profile.
|
||||
Probes are real requests (may consume tokens and trigger rate limits).
|
||||
Use `--agent <id>` to inspect a configured agent’s model/auth state. When omitted,
|
||||
the command uses `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR` if set, otherwise the
|
||||
configured default agent.
|
||||
Probe rows can come from auth profiles, env credentials, or `models.json`.
|
||||
|
||||
Notes:
|
||||
|
||||
- `models set <model-or-alias>` accepts `provider/model` or an alias.
|
||||
- Model refs are parsed by splitting on the **first** `/`. If the model ID includes `/` (OpenRouter-style), include the provider prefix (example: `openrouter/moonshotai/kimi-k2`).
|
||||
- If you omit the provider, OpenClaw resolves the input as an alias first, then
|
||||
as a unique configured-provider match for that exact model id, and only then
|
||||
falls back to the configured default provider with a deprecation warning.
|
||||
If that provider no longer exposes the configured default model, OpenClaw
|
||||
falls back to the first configured provider/model instead of surfacing a
|
||||
stale removed-provider default.
|
||||
- `models status` may show `marker(<value>)` in auth output for non-secret placeholders (for example `OPENAI_API_KEY`, `secretref-managed`, `minimax-oauth`, `oauth:chutes`, `ollama-local`) instead of masking them as secrets.
|
||||
|
||||
### `models status`
|
||||
|
||||
Options:
|
||||
|
||||
- `--json`
|
||||
- `--plain`
|
||||
- `--check` (exit 1=expired/missing, 2=expiring)
|
||||
- `--probe` (live probe of configured auth profiles)
|
||||
- `--probe-provider <name>` (probe one provider)
|
||||
- `--probe-profile <id>` (repeat or comma-separated profile ids)
|
||||
- `--probe-timeout <ms>`
|
||||
- `--probe-concurrency <n>`
|
||||
- `--probe-max-tokens <n>`
|
||||
- `--agent <id>` (configured agent id; overrides `OPENCLAW_AGENT_DIR`/`PI_CODING_AGENT_DIR`)
|
||||
|
||||
Probe status buckets:
|
||||
|
||||
- `ok`
|
||||
- `auth`
|
||||
- `rate_limit`
|
||||
- `billing`
|
||||
- `timeout`
|
||||
- `format`
|
||||
- `unknown`
|
||||
- `no_model`
|
||||
|
||||
Probe detail/reason-code cases to expect:
|
||||
|
||||
- `excluded_by_auth_order`: a stored profile exists, but explicit
|
||||
`auth.order.<provider>` omitted it, so probe reports the exclusion instead of
|
||||
trying it.
|
||||
- `missing_credential`, `invalid_expires`, `expired`, `unresolved_ref`:
|
||||
profile is present but not eligible/resolvable.
|
||||
- `no_model`: provider auth exists, but OpenClaw could not resolve a probeable
|
||||
model candidate for that provider.
|
||||
|
||||
## Aliases + fallbacks
|
||||
|
||||
```bash
|
||||
openclaw models aliases list
|
||||
openclaw models fallbacks list
|
||||
```
|
||||
|
||||
## Auth profiles
|
||||
|
||||
```bash
|
||||
openclaw models auth add
|
||||
openclaw models auth login --provider <id>
|
||||
openclaw models auth setup-token --provider <id>
|
||||
openclaw models auth paste-token
|
||||
```
|
||||
|
||||
`models auth add` is the interactive auth helper. It can launch a provider auth
|
||||
flow (OAuth/API key) or guide you into manual token paste, depending on the
|
||||
provider you choose.
|
||||
|
||||
`models auth login` runs a provider plugin’s auth flow (OAuth/API key). Use
|
||||
`openclaw plugins list` to see which providers are installed.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --set-default
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `setup-token` and `paste-token` remain generic token commands for providers
|
||||
that expose token auth methods.
|
||||
- `setup-token` requires an interactive TTY and runs the provider's token-auth
|
||||
method (defaulting to that provider's `setup-token` method when it exposes
|
||||
one).
|
||||
- `paste-token` accepts a token string generated elsewhere or from automation.
|
||||
- `paste-token` requires `--provider`, prompts for the token value, and writes
|
||||
it to the default profile id `<provider>:manual` unless you pass
|
||||
`--profile-id`.
|
||||
- `paste-token --expires-in <duration>` stores an absolute token expiry from a
|
||||
relative duration such as `365d` or `12h`.
|
||||
- Anthropic note: Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.
|
||||
- Anthropic `setup-token` / `paste-token` remain available as a supported OpenClaw token path, but OpenClaw now prefers Claude CLI reuse and `claude -p` when available.
|
||||
137
openclaw/docs/cli/node.md
Normal file
137
openclaw/docs/cli/node.md
Normal file
|
|
@ -0,0 +1,137 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw node` (headless node host)"
|
||||
read_when:
|
||||
- Running the headless node host
|
||||
- Pairing a non-macOS node for system.run
|
||||
title: "node"
|
||||
---
|
||||
|
||||
# `openclaw node`
|
||||
|
||||
Run a **headless node host** that connects to the Gateway WebSocket and exposes
|
||||
`system.run` / `system.which` on this machine.
|
||||
|
||||
## Why use a node host?
|
||||
|
||||
Use a node host when you want agents to **run commands on other machines** in your
|
||||
network without installing a full macOS companion app there.
|
||||
|
||||
Common use cases:
|
||||
|
||||
- Run commands on remote Linux/Windows boxes (build servers, lab machines, NAS).
|
||||
- Keep exec **sandboxed** on the gateway, but delegate approved runs to other hosts.
|
||||
- Provide a lightweight, headless execution target for automation or CI nodes.
|
||||
|
||||
Execution is still guarded by **exec approvals** and per‑agent allowlists on the
|
||||
node host, so you can keep command access scoped and explicit.
|
||||
|
||||
## Browser proxy (zero-config)
|
||||
|
||||
Node hosts automatically advertise a browser proxy if `browser.enabled` is not
|
||||
disabled on the node. This lets the agent use browser automation on that node
|
||||
without extra configuration.
|
||||
|
||||
By default, the proxy exposes the node's normal browser profile surface. If you
|
||||
set `nodeHost.browserProxy.allowProfiles`, the proxy becomes restrictive:
|
||||
non-allowlisted profile targeting is rejected, and persistent profile
|
||||
create/delete routes are blocked through the proxy.
|
||||
|
||||
Disable it on the node if needed:
|
||||
|
||||
```json5
|
||||
{
|
||||
nodeHost: {
|
||||
browserProxy: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Run (foreground)
|
||||
|
||||
```bash
|
||||
openclaw node run --host <gateway-host> --port 18789
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
|
||||
- `--port <port>`: Gateway WebSocket port (default: `18789`)
|
||||
- `--tls`: Use TLS for the gateway connection
|
||||
- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
|
||||
- `--node-id <id>`: Override node id (clears pairing token)
|
||||
- `--display-name <name>`: Override the node display name
|
||||
|
||||
## Gateway auth for node host
|
||||
|
||||
`openclaw node run` and `openclaw node install` resolve gateway auth from config/env (no `--token`/`--password` flags on node commands):
|
||||
|
||||
- `OPENCLAW_GATEWAY_TOKEN` / `OPENCLAW_GATEWAY_PASSWORD` are checked first.
|
||||
- Then local config fallback: `gateway.auth.token` / `gateway.auth.password`.
|
||||
- In local mode, node host intentionally does not inherit `gateway.remote.token` / `gateway.remote.password`.
|
||||
- If `gateway.auth.token` / `gateway.auth.password` is explicitly configured via SecretRef and unresolved, node auth resolution fails closed (no remote fallback masking).
|
||||
- In `gateway.mode=remote`, remote client fields (`gateway.remote.token` / `gateway.remote.password`) are also eligible per remote precedence rules.
|
||||
- Node host auth resolution only honors `OPENCLAW_GATEWAY_*` env vars.
|
||||
|
||||
## Service (background)
|
||||
|
||||
Install a headless node host as a user service.
|
||||
|
||||
```bash
|
||||
openclaw node install --host <gateway-host> --port 18789
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--host <host>`: Gateway WebSocket host (default: `127.0.0.1`)
|
||||
- `--port <port>`: Gateway WebSocket port (default: `18789`)
|
||||
- `--tls`: Use TLS for the gateway connection
|
||||
- `--tls-fingerprint <sha256>`: Expected TLS certificate fingerprint (sha256)
|
||||
- `--node-id <id>`: Override node id (clears pairing token)
|
||||
- `--display-name <name>`: Override the node display name
|
||||
- `--runtime <runtime>`: Service runtime (`node` or `bun`)
|
||||
- `--force`: Reinstall/overwrite if already installed
|
||||
|
||||
Manage the service:
|
||||
|
||||
```bash
|
||||
openclaw node status
|
||||
openclaw node stop
|
||||
openclaw node restart
|
||||
openclaw node uninstall
|
||||
```
|
||||
|
||||
Use `openclaw node run` for a foreground node host (no service).
|
||||
|
||||
Service commands accept `--json` for machine-readable output.
|
||||
|
||||
## Pairing
|
||||
|
||||
The first connection creates a pending device pairing request (`role: node`) on the Gateway.
|
||||
Approve it via:
|
||||
|
||||
```bash
|
||||
openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
|
||||
If the node retries pairing with changed auth details (role/scopes/public key),
|
||||
the previous pending request is superseded and a new `requestId` is created.
|
||||
Run `openclaw devices list` again before approval.
|
||||
|
||||
The node host stores its node id, token, display name, and gateway connection info in
|
||||
`~/.openclaw/node.json`.
|
||||
|
||||
## Exec approvals
|
||||
|
||||
`system.run` is gated by local exec approvals:
|
||||
|
||||
- `~/.openclaw/exec-approvals.json`
|
||||
- [Exec approvals](/tools/exec-approvals)
|
||||
- `openclaw approvals --node <id|name|ip>` (edit from the Gateway)
|
||||
|
||||
For approved async node exec, OpenClaw prepares a canonical `systemRunPlan`
|
||||
before prompting. The later approved `system.run` forward reuses that stored
|
||||
plan, so edits to command/cwd/session fields after the approval request was
|
||||
created are rejected instead of changing what the node executes.
|
||||
66
openclaw/docs/cli/nodes.md
Normal file
66
openclaw/docs/cli/nodes.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw nodes` (status, pairing, invoke, camera/canvas/screen)"
|
||||
read_when:
|
||||
- You’re managing paired nodes (cameras, screen, canvas)
|
||||
- You need to approve requests or invoke node commands
|
||||
title: "nodes"
|
||||
---
|
||||
|
||||
# `openclaw nodes`
|
||||
|
||||
Manage paired nodes (devices) and invoke node capabilities.
|
||||
|
||||
Related:
|
||||
|
||||
- Nodes overview: [Nodes](/nodes)
|
||||
- Camera: [Camera nodes](/nodes/camera)
|
||||
- Images: [Image nodes](/nodes/images)
|
||||
|
||||
Common options:
|
||||
|
||||
- `--url`, `--token`, `--timeout`, `--json`
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw nodes list
|
||||
openclaw nodes list --connected
|
||||
openclaw nodes list --last-connected 24h
|
||||
openclaw nodes pending
|
||||
openclaw nodes approve <requestId>
|
||||
openclaw nodes reject <requestId>
|
||||
openclaw nodes rename --node <id|name|ip> --name <displayName>
|
||||
openclaw nodes status
|
||||
openclaw nodes status --connected
|
||||
openclaw nodes status --last-connected 24h
|
||||
```
|
||||
|
||||
`nodes list` prints pending/paired tables. Paired rows include the most recent connect age (Last Connect).
|
||||
Use `--connected` to only show currently-connected nodes. Use `--last-connected <duration>` to
|
||||
filter to nodes that connected within a duration (e.g. `24h`, `7d`).
|
||||
|
||||
Approval note:
|
||||
|
||||
- `openclaw nodes pending` only needs pairing scope.
|
||||
- `openclaw nodes approve <requestId>` inherits extra scope requirements from the
|
||||
pending request:
|
||||
- commandless request: pairing only
|
||||
- non-exec node commands: pairing + write
|
||||
- `system.run` / `system.run.prepare` / `system.which`: pairing + admin
|
||||
|
||||
## Invoke
|
||||
|
||||
```bash
|
||||
openclaw nodes invoke --node <id|name|ip> --command <command> --params <json>
|
||||
```
|
||||
|
||||
Invoke flags:
|
||||
|
||||
- `--params <json>`: JSON object string (default `{}`).
|
||||
- `--invoke-timeout <ms>`: node invoke timeout (default `15000`).
|
||||
- `--idempotency-key <key>`: optional idempotency key.
|
||||
- `system.run` and `system.run.prepare` are blocked here; use the `exec` tool with `host=node` for shell execution.
|
||||
|
||||
For shell execution on a node, use the `exec` tool with `host=node` instead of `openclaw nodes run`.
|
||||
The `nodes` CLI is now capability-focused: direct RPC via `nodes invoke`, plus pairing, camera,
|
||||
screen, location, canvas, and notifications.
|
||||
182
openclaw/docs/cli/onboard.md
Normal file
182
openclaw/docs/cli/onboard.md
Normal file
|
|
@ -0,0 +1,182 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw onboard` (interactive onboarding)"
|
||||
read_when:
|
||||
- You want guided setup for gateway, workspace, auth, channels, and skills
|
||||
title: "onboard"
|
||||
---
|
||||
|
||||
# `openclaw onboard`
|
||||
|
||||
Interactive onboarding for local or remote Gateway setup.
|
||||
|
||||
## Related guides
|
||||
|
||||
- CLI onboarding hub: [Onboarding (CLI)](/start/wizard)
|
||||
- Onboarding overview: [Onboarding Overview](/start/onboarding-overview)
|
||||
- CLI onboarding reference: [CLI Setup Reference](/start/wizard-cli-reference)
|
||||
- CLI automation: [CLI Automation](/start/wizard-cli-automation)
|
||||
- macOS onboarding: [Onboarding (macOS App)](/start/onboarding)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
openclaw onboard --flow quickstart
|
||||
openclaw onboard --flow manual
|
||||
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
|
||||
```
|
||||
|
||||
For plaintext private-network `ws://` targets (trusted networks only), set
|
||||
`OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1` in the onboarding process environment.
|
||||
|
||||
Non-interactive custom provider:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice custom-api-key \
|
||||
--custom-base-url "https://llm.example.com/v1" \
|
||||
--custom-model-id "foo-large" \
|
||||
--custom-api-key "$CUSTOM_API_KEY" \
|
||||
--secret-input-mode plaintext \
|
||||
--custom-compatibility openai
|
||||
```
|
||||
|
||||
`--custom-api-key` is optional in non-interactive mode. If omitted, onboarding checks `CUSTOM_API_KEY`.
|
||||
|
||||
LM Studio also supports a provider-specific key flag in non-interactive mode:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice lmstudio \
|
||||
--custom-base-url "http://localhost:1234/v1" \
|
||||
--custom-model-id "qwen/qwen3.5-9b" \
|
||||
--lmstudio-api-key "$LM_API_TOKEN" \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
Non-interactive Ollama:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice ollama \
|
||||
--custom-base-url "http://ollama-host:11434" \
|
||||
--custom-model-id "qwen3.5:27b" \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
`--custom-base-url` defaults to `http://127.0.0.1:11434`. `--custom-model-id` is optional; if omitted, onboarding uses Ollama's suggested defaults. Cloud model IDs such as `kimi-k2.5:cloud` also work here.
|
||||
|
||||
Store provider keys as refs instead of plaintext:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice openai-api-key \
|
||||
--secret-input-mode ref \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
With `--secret-input-mode ref`, onboarding writes env-backed refs instead of plaintext key values.
|
||||
For auth-profile backed providers this writes `keyRef` entries; for custom providers this writes `models.providers.<id>.apiKey` as an env ref (for example `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`).
|
||||
|
||||
Non-interactive `ref` mode contract:
|
||||
|
||||
- Set the provider env var in the onboarding process environment (for example `OPENAI_API_KEY`).
|
||||
- Do not pass inline key flags (for example `--openai-api-key`) unless that env var is also set.
|
||||
- If an inline key flag is passed without the required env var, onboarding fails fast with guidance.
|
||||
|
||||
Gateway token options in non-interactive mode:
|
||||
|
||||
- `--gateway-auth token --gateway-token <token>` stores a plaintext token.
|
||||
- `--gateway-auth token --gateway-token-ref-env <name>` stores `gateway.auth.token` as an env SecretRef.
|
||||
- `--gateway-token` and `--gateway-token-ref-env` are mutually exclusive.
|
||||
- `--gateway-token-ref-env` requires a non-empty env var in the onboarding process environment.
|
||||
- With `--install-daemon`, when token auth requires a token, SecretRef-managed gateway tokens are validated but not persisted as resolved plaintext in supervisor service environment metadata.
|
||||
- With `--install-daemon`, if token mode requires a token and the configured token SecretRef is unresolved, onboarding fails closed with remediation guidance.
|
||||
- With `--install-daemon`, if both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, onboarding blocks install until mode is set explicitly.
|
||||
- Local onboarding writes `gateway.mode="local"` into the config. If a later config file is missing `gateway.mode`, treat that as config damage or an incomplete manual edit, not as a valid local-mode shortcut.
|
||||
- `--allow-unconfigured` is a separate gateway runtime escape hatch. It does not mean onboarding may omit `gateway.mode`.
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
export OPENCLAW_GATEWAY_TOKEN="your-token"
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
--auth-choice skip \
|
||||
--gateway-auth token \
|
||||
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
Non-interactive local gateway health:
|
||||
|
||||
- Unless you pass `--skip-health`, onboarding waits for a reachable local gateway before it exits successfully.
|
||||
- `--install-daemon` starts the managed gateway install path first. Without it, you must already have a local gateway running, for example `openclaw gateway run`.
|
||||
- If you only want config/workspace/bootstrap writes in automation, use `--skip-health`.
|
||||
- On native Windows, `--install-daemon` tries Scheduled Tasks first and falls back to a per-user Startup-folder login item if task creation is denied.
|
||||
|
||||
Interactive onboarding behavior with reference mode:
|
||||
|
||||
- Choose **Use secret reference** when prompted.
|
||||
- Then choose either:
|
||||
- Environment variable
|
||||
- Configured secret provider (`file` or `exec`)
|
||||
- Onboarding performs a fast preflight validation before saving the ref.
|
||||
- If validation fails, onboarding shows the error and lets you retry.
|
||||
|
||||
Non-interactive Z.AI endpoint choices:
|
||||
|
||||
Note: `--auth-choice zai-api-key` now auto-detects the best Z.AI endpoint for your key (prefers the general API with `zai/glm-5.1`).
|
||||
If you specifically want the GLM Coding Plan endpoints, pick `zai-coding-global` or `zai-coding-cn`.
|
||||
|
||||
```bash
|
||||
# Promptless endpoint selection
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice zai-coding-global \
|
||||
--zai-api-key "$ZAI_API_KEY"
|
||||
|
||||
# Other Z.AI endpoint choices:
|
||||
# --auth-choice zai-coding-cn
|
||||
# --auth-choice zai-global
|
||||
# --auth-choice zai-cn
|
||||
```
|
||||
|
||||
Non-interactive Mistral example:
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--auth-choice mistral-api-key \
|
||||
--mistral-api-key "$MISTRAL_API_KEY"
|
||||
```
|
||||
|
||||
Flow notes:
|
||||
|
||||
- `quickstart`: minimal prompts, auto-generates a gateway token.
|
||||
- `manual`: full prompts for port/bind/auth (alias of `advanced`).
|
||||
- When an auth choice implies a preferred provider, onboarding prefilters the
|
||||
default-model and allowlist pickers to that provider. For Volcengine and
|
||||
BytePlus, this also matches the coding-plan variants
|
||||
(`volcengine-plan/*`, `byteplus-plan/*`).
|
||||
- If the preferred-provider filter yields no loaded models yet, onboarding
|
||||
falls back to the unfiltered catalog instead of leaving the picker empty.
|
||||
- In the web-search step, some providers can trigger provider-specific
|
||||
follow-up prompts:
|
||||
- **Grok** can offer optional `x_search` setup with the same `XAI_API_KEY`
|
||||
and an `x_search` model choice.
|
||||
- **Kimi** can ask for the Moonshot API region (`api.moonshot.ai` vs
|
||||
`api.moonshot.cn`) and the default Kimi web-search model.
|
||||
- Local onboarding DM scope behavior: [CLI Setup Reference](/start/wizard-cli-reference#outputs-and-internals).
|
||||
- Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
|
||||
- Custom Provider: connect any OpenAI or Anthropic compatible endpoint,
|
||||
including hosted providers not listed. Use Unknown to auto-detect.
|
||||
|
||||
## Common follow-up commands
|
||||
|
||||
```bash
|
||||
openclaw configure
|
||||
openclaw agents add <name>
|
||||
```
|
||||
|
||||
<Note>
|
||||
`--json` does not imply non-interactive mode. Use `--non-interactive` for scripts.
|
||||
</Note>
|
||||
65
openclaw/docs/cli/pairing.md
Normal file
65
openclaw/docs/cli/pairing.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw pairing` (approve/list pairing requests)"
|
||||
read_when:
|
||||
- You’re using pairing-mode DMs and need to approve senders
|
||||
title: "pairing"
|
||||
---
|
||||
|
||||
# `openclaw pairing`
|
||||
|
||||
Approve or inspect DM pairing requests (for channels that support pairing).
|
||||
|
||||
Related:
|
||||
|
||||
- Pairing flow: [Pairing](/channels/pairing)
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
openclaw pairing list telegram
|
||||
openclaw pairing list --channel telegram --account work
|
||||
openclaw pairing list telegram --json
|
||||
|
||||
openclaw pairing approve <code>
|
||||
openclaw pairing approve telegram <code>
|
||||
openclaw pairing approve --channel telegram --account work <code> --notify
|
||||
```
|
||||
|
||||
## `pairing list`
|
||||
|
||||
List pending pairing requests for one channel.
|
||||
|
||||
Options:
|
||||
|
||||
- `[channel]`: positional channel id
|
||||
- `--channel <channel>`: explicit channel id
|
||||
- `--account <accountId>`: account id for multi-account channels
|
||||
- `--json`: machine-readable output
|
||||
|
||||
Notes:
|
||||
|
||||
- If multiple pairing-capable channels are configured, you must provide a channel either positionally or with `--channel`.
|
||||
- Extension channels are allowed as long as the channel id is valid.
|
||||
|
||||
## `pairing approve`
|
||||
|
||||
Approve a pending pairing code and allow that sender.
|
||||
|
||||
Usage:
|
||||
|
||||
- `openclaw pairing approve <channel> <code>`
|
||||
- `openclaw pairing approve --channel <channel> <code>`
|
||||
- `openclaw pairing approve <code>` when exactly one pairing-capable channel is configured
|
||||
|
||||
Options:
|
||||
|
||||
- `--channel <channel>`: explicit channel id
|
||||
- `--account <accountId>`: account id for multi-account channels
|
||||
- `--notify`: send a confirmation back to the requester on the same channel
|
||||
|
||||
## Notes
|
||||
|
||||
- Channel input: pass it positionally (`pairing list telegram`) or with `--channel <channel>`.
|
||||
- `pairing list` supports `--account <accountId>` for multi-account channels.
|
||||
- `pairing approve` supports `--account <accountId>` and `--notify`.
|
||||
- If only one pairing-capable channel is configured, `pairing approve <code>` is allowed.
|
||||
305
openclaw/docs/cli/plugins.md
Normal file
305
openclaw/docs/cli/plugins.md
Normal file
|
|
@ -0,0 +1,305 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw plugins` (list, install, marketplace, uninstall, enable/disable, doctor)"
|
||||
read_when:
|
||||
- You want to install or manage Gateway plugins or compatible bundles
|
||||
- You want to debug plugin load failures
|
||||
title: "plugins"
|
||||
---
|
||||
|
||||
# `openclaw plugins`
|
||||
|
||||
Manage Gateway plugins/extensions, hook packs, and compatible bundles.
|
||||
|
||||
Related:
|
||||
|
||||
- Plugin system: [Plugins](/tools/plugin)
|
||||
- Bundle compatibility: [Plugin bundles](/plugins/bundles)
|
||||
- Plugin manifest + schema: [Plugin manifest](/plugins/manifest)
|
||||
- Security hardening: [Security](/gateway/security)
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
openclaw plugins list --enabled
|
||||
openclaw plugins list --verbose
|
||||
openclaw plugins list --json
|
||||
openclaw plugins install <path-or-spec>
|
||||
openclaw plugins inspect <id>
|
||||
openclaw plugins inspect <id> --json
|
||||
openclaw plugins inspect --all
|
||||
openclaw plugins info <id>
|
||||
openclaw plugins enable <id>
|
||||
openclaw plugins disable <id>
|
||||
openclaw plugins uninstall <id>
|
||||
openclaw plugins doctor
|
||||
openclaw plugins update <id>
|
||||
openclaw plugins update --all
|
||||
openclaw plugins marketplace list <marketplace>
|
||||
openclaw plugins marketplace list <marketplace> --json
|
||||
```
|
||||
|
||||
Bundled plugins ship with OpenClaw. Some are enabled by default (for example
|
||||
bundled model providers, bundled speech providers, and the bundled browser
|
||||
plugin); others require `plugins enable`.
|
||||
|
||||
Native OpenClaw plugins must ship `openclaw.plugin.json` with an inline JSON
|
||||
Schema (`configSchema`, even if empty). Compatible bundles use their own bundle
|
||||
manifests instead.
|
||||
|
||||
`plugins list` shows `Format: openclaw` or `Format: bundle`. Verbose list/info
|
||||
output also shows the bundle subtype (`codex`, `claude`, or `cursor`) plus detected bundle
|
||||
capabilities.
|
||||
|
||||
### Install
|
||||
|
||||
```bash
|
||||
openclaw plugins install <package> # ClawHub first, then npm
|
||||
openclaw plugins install clawhub:<package> # ClawHub only
|
||||
openclaw plugins install <package> --force # overwrite existing install
|
||||
openclaw plugins install <package> --pin # pin version
|
||||
openclaw plugins install <package> --dangerously-force-unsafe-install
|
||||
openclaw plugins install <path> # local path
|
||||
openclaw plugins install <plugin>@<marketplace> # marketplace
|
||||
openclaw plugins install <plugin> --marketplace <name> # marketplace (explicit)
|
||||
openclaw plugins install <plugin> --marketplace https://github.com/<owner>/<repo>
|
||||
```
|
||||
|
||||
Bare package names are checked against ClawHub first, then npm. Security note:
|
||||
treat plugin installs like running code. Prefer pinned versions.
|
||||
|
||||
If config is invalid, `plugins install` normally fails closed and tells you to
|
||||
run `openclaw doctor --fix` first. The only documented exception is a narrow
|
||||
bundled-plugin recovery path for plugins that explicitly opt into
|
||||
`openclaw.install.allowInvalidConfigRecovery`.
|
||||
|
||||
`--force` reuses the existing install target and overwrites an already-installed
|
||||
plugin or hook pack in place. Use it when you are intentionally reinstalling
|
||||
the same id from a new local path, archive, ClawHub package, or npm artifact.
|
||||
|
||||
`--pin` applies to npm installs only. It is not supported with `--marketplace`,
|
||||
because marketplace installs persist marketplace source metadata instead of an
|
||||
npm spec.
|
||||
|
||||
`--dangerously-force-unsafe-install` is a break-glass option for false positives
|
||||
in the built-in dangerous-code scanner. It allows the install to continue even
|
||||
when the built-in scanner reports `critical` findings, but it does **not**
|
||||
bypass plugin `before_install` hook policy blocks and does **not** bypass scan
|
||||
failures.
|
||||
|
||||
This CLI flag applies to plugin install/update flows. Gateway-backed skill
|
||||
dependency installs use the matching `dangerouslyForceUnsafeInstall` request
|
||||
override, while `openclaw skills install` remains a separate ClawHub skill
|
||||
download/install flow.
|
||||
|
||||
`plugins install` is also the install surface for hook packs that expose
|
||||
`openclaw.hooks` in `package.json`. Use `openclaw hooks` for filtered hook
|
||||
visibility and per-hook enablement, not package installation.
|
||||
|
||||
Npm specs are **registry-only** (package name + optional **exact version** or
|
||||
**dist-tag**). Git/URL/file specs and semver ranges are rejected. Dependency
|
||||
installs run with `--ignore-scripts` for safety.
|
||||
|
||||
Bare specs and `@latest` stay on the stable track. If npm resolves either of
|
||||
those to a prerelease, OpenClaw stops and asks you to opt in explicitly with a
|
||||
prerelease tag such as `@beta`/`@rc` or an exact prerelease version such as
|
||||
`@1.2.3-beta.4`.
|
||||
|
||||
If a bare install spec matches a bundled plugin id (for example `diffs`), OpenClaw
|
||||
installs the bundled plugin directly. To install an npm package with the same
|
||||
name, use an explicit scoped spec (for example `@scope/diffs`).
|
||||
|
||||
Supported archives: `.zip`, `.tgz`, `.tar.gz`, `.tar`.
|
||||
|
||||
Claude marketplace installs are also supported.
|
||||
|
||||
ClawHub installs use an explicit `clawhub:<package>` locator:
|
||||
|
||||
```bash
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server
|
||||
openclaw plugins install clawhub:openclaw-codex-app-server@1.2.3
|
||||
```
|
||||
|
||||
OpenClaw now also prefers ClawHub for bare npm-safe plugin specs. It only falls
|
||||
back to npm if ClawHub does not have that package or version:
|
||||
|
||||
```bash
|
||||
openclaw plugins install openclaw-codex-app-server
|
||||
```
|
||||
|
||||
OpenClaw downloads the package archive from ClawHub, checks the advertised
|
||||
plugin API / minimum gateway compatibility, then installs it through the normal
|
||||
archive path. Recorded installs keep their ClawHub source metadata for later
|
||||
updates.
|
||||
|
||||
Use `plugin@marketplace` shorthand when the marketplace name exists in Claude's
|
||||
local registry cache at `~/.claude/plugins/known_marketplaces.json`:
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <marketplace-name>
|
||||
openclaw plugins install <plugin-name>@<marketplace-name>
|
||||
```
|
||||
|
||||
Use `--marketplace` when you want to pass the marketplace source explicitly:
|
||||
|
||||
```bash
|
||||
openclaw plugins install <plugin-name> --marketplace <marketplace-name>
|
||||
openclaw plugins install <plugin-name> --marketplace <owner/repo>
|
||||
openclaw plugins install <plugin-name> --marketplace https://github.com/<owner>/<repo>
|
||||
openclaw plugins install <plugin-name> --marketplace ./my-marketplace
|
||||
```
|
||||
|
||||
Marketplace sources can be:
|
||||
|
||||
- a Claude known-marketplace name from `~/.claude/plugins/known_marketplaces.json`
|
||||
- a local marketplace root or `marketplace.json` path
|
||||
- a GitHub repo shorthand such as `owner/repo`
|
||||
- a GitHub repo URL such as `https://github.com/owner/repo`
|
||||
- a git URL
|
||||
|
||||
For remote marketplaces loaded from GitHub or git, plugin entries must stay
|
||||
inside the cloned marketplace repo. OpenClaw accepts relative path sources from
|
||||
that repo and rejects HTTP(S), absolute-path, git, GitHub, and other non-path
|
||||
plugin sources from remote manifests.
|
||||
|
||||
For local paths and archives, OpenClaw auto-detects:
|
||||
|
||||
- native OpenClaw plugins (`openclaw.plugin.json`)
|
||||
- Codex-compatible bundles (`.codex-plugin/plugin.json`)
|
||||
- Claude-compatible bundles (`.claude-plugin/plugin.json` or the default Claude
|
||||
component layout)
|
||||
- Cursor-compatible bundles (`.cursor-plugin/plugin.json`)
|
||||
|
||||
Compatible bundles install into the normal extensions root and participate in
|
||||
the same list/info/enable/disable flow. Today, bundle skills, Claude
|
||||
command-skills, Claude `settings.json` defaults, Claude `.lsp.json` /
|
||||
manifest-declared `lspServers` defaults, Cursor command-skills, and compatible
|
||||
Codex hook directories are supported; other detected bundle capabilities are
|
||||
shown in diagnostics/info but are not yet wired into runtime execution.
|
||||
|
||||
### List
|
||||
|
||||
```bash
|
||||
openclaw plugins list
|
||||
openclaw plugins list --enabled
|
||||
openclaw plugins list --verbose
|
||||
openclaw plugins list --json
|
||||
```
|
||||
|
||||
Use `--enabled` to show only loaded plugins. Use `--verbose` to switch from the
|
||||
table view to per-plugin detail lines with source/origin/version/activation
|
||||
metadata. Use `--json` for machine-readable inventory plus registry
|
||||
diagnostics.
|
||||
|
||||
Use `--link` to avoid copying a local directory (adds to `plugins.load.paths`):
|
||||
|
||||
```bash
|
||||
openclaw plugins install -l ./my-plugin
|
||||
```
|
||||
|
||||
`--force` is not supported with `--link` because linked installs reuse the
|
||||
source path instead of copying over a managed install target.
|
||||
|
||||
Use `--pin` on npm installs to save the resolved exact spec (`name@version`) in
|
||||
`plugins.installs` while keeping the default behavior unpinned.
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
openclaw plugins uninstall <id>
|
||||
openclaw plugins uninstall <id> --dry-run
|
||||
openclaw plugins uninstall <id> --keep-files
|
||||
```
|
||||
|
||||
`uninstall` removes plugin records from `plugins.entries`, `plugins.installs`,
|
||||
the plugin allowlist, and linked `plugins.load.paths` entries when applicable.
|
||||
For active memory plugins, the memory slot resets to `memory-core`.
|
||||
|
||||
By default, uninstall also removes the plugin install directory under the active
|
||||
state-dir plugin root. Use
|
||||
`--keep-files` to keep files on disk.
|
||||
|
||||
`--keep-config` is supported as a deprecated alias for `--keep-files`.
|
||||
|
||||
### Update
|
||||
|
||||
```bash
|
||||
openclaw plugins update <id-or-npm-spec>
|
||||
openclaw plugins update --all
|
||||
openclaw plugins update <id-or-npm-spec> --dry-run
|
||||
openclaw plugins update @openclaw/voice-call@beta
|
||||
openclaw plugins update openclaw-codex-app-server --dangerously-force-unsafe-install
|
||||
```
|
||||
|
||||
Updates apply to tracked installs in `plugins.installs` and tracked hook-pack
|
||||
installs in `hooks.internal.installs`.
|
||||
|
||||
When you pass a plugin id, OpenClaw reuses the recorded install spec for that
|
||||
plugin. That means previously stored dist-tags such as `@beta` and exact pinned
|
||||
versions continue to be used on later `update <id>` runs.
|
||||
|
||||
For npm installs, you can also pass an explicit npm package spec with a dist-tag
|
||||
or exact version. OpenClaw resolves that package name back to the tracked plugin
|
||||
record, updates that installed plugin, and records the new npm spec for future
|
||||
id-based updates.
|
||||
|
||||
When a stored integrity hash exists and the fetched artifact hash changes,
|
||||
OpenClaw prints a warning and asks for confirmation before proceeding. Use
|
||||
global `--yes` to bypass prompts in CI/non-interactive runs.
|
||||
|
||||
`--dangerously-force-unsafe-install` is also available on `plugins update` as a
|
||||
break-glass override for built-in dangerous-code scan false positives during
|
||||
plugin updates. It still does not bypass plugin `before_install` policy blocks
|
||||
or scan-failure blocking, and it only applies to plugin updates, not hook-pack
|
||||
updates.
|
||||
|
||||
### Inspect
|
||||
|
||||
```bash
|
||||
openclaw plugins inspect <id>
|
||||
openclaw plugins inspect <id> --json
|
||||
```
|
||||
|
||||
Deep introspection for a single plugin. Shows identity, load status, source,
|
||||
registered capabilities, hooks, tools, commands, services, gateway methods,
|
||||
HTTP routes, policy flags, diagnostics, install metadata, bundle capabilities,
|
||||
and any detected MCP or LSP server support.
|
||||
|
||||
Each plugin is classified by what it actually registers at runtime:
|
||||
|
||||
- **plain-capability** — one capability type (e.g. a provider-only plugin)
|
||||
- **hybrid-capability** — multiple capability types (e.g. text + speech + images)
|
||||
- **hook-only** — only hooks, no capabilities or surfaces
|
||||
- **non-capability** — tools/commands/services but no capabilities
|
||||
|
||||
See [Plugin shapes](/plugins/architecture#plugin-shapes) for more on the capability model.
|
||||
|
||||
The `--json` flag outputs a machine-readable report suitable for scripting and
|
||||
auditing.
|
||||
|
||||
`inspect --all` renders a fleet-wide table with shape, capability kinds,
|
||||
compatibility notices, bundle capabilities, and hook summary columns.
|
||||
|
||||
`info` is an alias for `inspect`.
|
||||
|
||||
### Doctor
|
||||
|
||||
```bash
|
||||
openclaw plugins doctor
|
||||
```
|
||||
|
||||
`doctor` reports plugin load errors, manifest/discovery diagnostics, and
|
||||
compatibility notices. When everything is clean it prints `No plugin issues
|
||||
detected.`
|
||||
|
||||
### Marketplace
|
||||
|
||||
```bash
|
||||
openclaw plugins marketplace list <source>
|
||||
openclaw plugins marketplace list <source> --json
|
||||
```
|
||||
|
||||
Marketplace list accepts a local marketplace path, a `marketplace.json` path, a
|
||||
GitHub shorthand like `owner/repo`, a GitHub repo URL, or a git URL. `--json`
|
||||
prints the resolved source label plus the parsed marketplace manifest and
|
||||
plugin entries.
|
||||
52
openclaw/docs/cli/qr.md
Normal file
52
openclaw/docs/cli/qr.md
Normal file
|
|
@ -0,0 +1,52 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw qr` (generate mobile pairing QR + setup code)"
|
||||
read_when:
|
||||
- You want to pair a mobile node app with a gateway quickly
|
||||
- You need setup-code output for remote/manual sharing
|
||||
title: "qr"
|
||||
---
|
||||
|
||||
# `openclaw qr`
|
||||
|
||||
Generate a mobile pairing QR and setup code from your current Gateway configuration.
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw qr
|
||||
openclaw qr --setup-code-only
|
||||
openclaw qr --json
|
||||
openclaw qr --remote
|
||||
openclaw qr --url wss://gateway.example/ws
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--remote`: prefer `gateway.remote.url`; if it is unset, `gateway.tailscale.mode=serve|funnel` can still provide the remote public URL
|
||||
- `--url <url>`: override gateway URL used in payload
|
||||
- `--public-url <url>`: override public URL used in payload
|
||||
- `--token <token>`: override which gateway token the bootstrap flow authenticates against
|
||||
- `--password <password>`: override which gateway password the bootstrap flow authenticates against
|
||||
- `--setup-code-only`: print only setup code
|
||||
- `--no-ascii`: skip ASCII QR rendering
|
||||
- `--json`: emit JSON (`setupCode`, `gatewayUrl`, `auth`, `urlSource`)
|
||||
|
||||
## Notes
|
||||
|
||||
- `--token` and `--password` are mutually exclusive.
|
||||
- The setup code itself now carries an opaque short-lived `bootstrapToken`, not the shared gateway token/password.
|
||||
- In the built-in node/operator bootstrap flow, the primary node token still lands with `scopes: []`.
|
||||
- If bootstrap handoff also issues an operator token, it stays bounded to the bootstrap allowlist: `operator.approvals`, `operator.read`, `operator.talk.secrets`, `operator.write`.
|
||||
- Bootstrap scope checks are role-prefixed. That operator allowlist only satisfies operator requests; non-operator roles still need scopes under their own role prefix.
|
||||
- Mobile pairing fails closed for Tailscale/public `ws://` gateway URLs. Private LAN `ws://` remains supported, but Tailscale/public mobile routes should use Tailscale Serve/Funnel or a `wss://` gateway URL.
|
||||
- With `--remote`, OpenClaw requires either `gateway.remote.url` or
|
||||
`gateway.tailscale.mode=serve|funnel`.
|
||||
- With `--remote`, if effectively active remote credentials are configured as SecretRefs and you do not pass `--token` or `--password`, the command resolves them from the active gateway snapshot. If gateway is unavailable, the command fails fast.
|
||||
- Without `--remote`, local gateway auth SecretRefs are resolved when no CLI auth override is passed:
|
||||
- `gateway.auth.token` resolves when token auth can win (explicit `gateway.auth.mode="token"` or inferred mode where no password source wins).
|
||||
- `gateway.auth.password` resolves when password auth can win (explicit `gateway.auth.mode="password"` or inferred mode with no winning token from auth/env).
|
||||
- If both `gateway.auth.token` and `gateway.auth.password` are configured (including SecretRefs) and `gateway.auth.mode` is unset, setup-code resolution fails until mode is set explicitly.
|
||||
- Gateway version skew note: this command path requires a gateway that supports `secrets.resolve`; older gateways return an unknown-method error.
|
||||
- After scanning, approve device pairing with:
|
||||
- `openclaw devices list`
|
||||
- `openclaw devices approve <requestId>`
|
||||
35
openclaw/docs/cli/reset.md
Normal file
35
openclaw/docs/cli/reset.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw reset` (reset local state/config)"
|
||||
read_when:
|
||||
- You want to wipe local state while keeping the CLI installed
|
||||
- You want a dry-run of what would be removed
|
||||
title: "reset"
|
||||
---
|
||||
|
||||
# `openclaw reset`
|
||||
|
||||
Reset local config/state (keeps the CLI installed).
|
||||
|
||||
Options:
|
||||
|
||||
- `--scope <scope>`: `config`, `config+creds+sessions`, or `full`
|
||||
- `--yes`: skip confirmation prompts
|
||||
- `--non-interactive`: disable prompts; requires `--scope` and `--yes`
|
||||
- `--dry-run`: print actions without removing files
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw backup create
|
||||
openclaw reset
|
||||
openclaw reset --dry-run
|
||||
openclaw reset --scope config --yes --non-interactive
|
||||
openclaw reset --scope config+creds+sessions --yes --non-interactive
|
||||
openclaw reset --scope full --yes --non-interactive
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Run `openclaw backup create` first if you want a restorable snapshot before removing local state.
|
||||
- If you omit `--scope`, `openclaw reset` uses an interactive prompt to choose what to remove.
|
||||
- `--non-interactive` is only valid when both `--scope` and `--yes` are set.
|
||||
197
openclaw/docs/cli/sandbox.md
Normal file
197
openclaw/docs/cli/sandbox.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
title: Sandbox CLI
|
||||
summary: "Manage sandbox runtimes and inspect effective sandbox policy"
|
||||
read_when: "You are managing sandbox runtimes or debugging sandbox/tool-policy behavior."
|
||||
status: active
|
||||
---
|
||||
|
||||
# Sandbox CLI
|
||||
|
||||
Manage sandbox runtimes for isolated agent execution.
|
||||
|
||||
## Overview
|
||||
|
||||
OpenClaw can run agents in isolated sandbox runtimes for security. The `sandbox` commands help you inspect and recreate those runtimes after updates or configuration changes.
|
||||
|
||||
Today that usually means:
|
||||
|
||||
- Docker sandbox containers
|
||||
- SSH sandbox runtimes when `agents.defaults.sandbox.backend = "ssh"`
|
||||
- OpenShell sandbox runtimes when `agents.defaults.sandbox.backend = "openshell"`
|
||||
|
||||
For `ssh` and OpenShell `remote`, recreate matters more than with Docker:
|
||||
|
||||
- the remote workspace is canonical after the initial seed
|
||||
- `openclaw sandbox recreate` deletes that canonical remote workspace for the selected scope
|
||||
- next use seeds it again from the current local workspace
|
||||
|
||||
## Commands
|
||||
|
||||
### `openclaw sandbox explain`
|
||||
|
||||
Inspect the **effective** sandbox mode/scope/workspace access, sandbox tool policy, and elevated gates (with fix-it config key paths).
|
||||
|
||||
```bash
|
||||
openclaw sandbox explain
|
||||
openclaw sandbox explain --session agent:main:main
|
||||
openclaw sandbox explain --agent work
|
||||
openclaw sandbox explain --json
|
||||
```
|
||||
|
||||
### `openclaw sandbox list`
|
||||
|
||||
List all sandbox runtimes with their status and configuration.
|
||||
|
||||
```bash
|
||||
openclaw sandbox list
|
||||
openclaw sandbox list --browser # List only browser containers
|
||||
openclaw sandbox list --json # JSON output
|
||||
```
|
||||
|
||||
**Output includes:**
|
||||
|
||||
- Runtime name and status
|
||||
- Backend (`docker`, `openshell`, etc.)
|
||||
- Config label and whether it matches current config
|
||||
- Age (time since creation)
|
||||
- Idle time (time since last use)
|
||||
- Associated session/agent
|
||||
|
||||
### `openclaw sandbox recreate`
|
||||
|
||||
Remove sandbox runtimes to force recreation with updated config.
|
||||
|
||||
```bash
|
||||
openclaw sandbox recreate --all # Recreate all containers
|
||||
openclaw sandbox recreate --session main # Specific session
|
||||
openclaw sandbox recreate --agent mybot # Specific agent
|
||||
openclaw sandbox recreate --browser # Only browser containers
|
||||
openclaw sandbox recreate --all --force # Skip confirmation
|
||||
```
|
||||
|
||||
**Options:**
|
||||
|
||||
- `--all`: Recreate all sandbox containers
|
||||
- `--session <key>`: Recreate container for specific session
|
||||
- `--agent <id>`: Recreate containers for specific agent
|
||||
- `--browser`: Only recreate browser containers
|
||||
- `--force`: Skip confirmation prompt
|
||||
|
||||
**Important:** Runtimes are automatically recreated when the agent is next used.
|
||||
|
||||
## Use Cases
|
||||
|
||||
### After updating a Docker image
|
||||
|
||||
```bash
|
||||
# Pull new image
|
||||
docker pull openclaw-sandbox:latest
|
||||
docker tag openclaw-sandbox:latest openclaw-sandbox:bookworm-slim
|
||||
|
||||
# Update config to use new image
|
||||
# Edit config: agents.defaults.sandbox.docker.image (or agents.list[].sandbox.docker.image)
|
||||
|
||||
# Recreate containers
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
### After changing sandbox configuration
|
||||
|
||||
```bash
|
||||
# Edit config: agents.defaults.sandbox.* (or agents.list[].sandbox.*)
|
||||
|
||||
# Recreate to apply new config
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
### After changing SSH target or SSH auth material
|
||||
|
||||
```bash
|
||||
# Edit config:
|
||||
# - agents.defaults.sandbox.backend
|
||||
# - agents.defaults.sandbox.ssh.target
|
||||
# - agents.defaults.sandbox.ssh.workspaceRoot
|
||||
# - agents.defaults.sandbox.ssh.identityFile / certificateFile / knownHostsFile
|
||||
# - agents.defaults.sandbox.ssh.identityData / certificateData / knownHostsData
|
||||
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
For the core `ssh` backend, recreate deletes the per-scope remote workspace root
|
||||
on the SSH target. The next run seeds it again from the local workspace.
|
||||
|
||||
### After changing OpenShell source, policy, or mode
|
||||
|
||||
```bash
|
||||
# Edit config:
|
||||
# - agents.defaults.sandbox.backend
|
||||
# - plugins.entries.openshell.config.from
|
||||
# - plugins.entries.openshell.config.mode
|
||||
# - plugins.entries.openshell.config.policy
|
||||
|
||||
openclaw sandbox recreate --all
|
||||
```
|
||||
|
||||
For OpenShell `remote` mode, recreate deletes the canonical remote workspace
|
||||
for that scope. The next run seeds it again from the local workspace.
|
||||
|
||||
### After changing setupCommand
|
||||
|
||||
```bash
|
||||
openclaw sandbox recreate --all
|
||||
# or just one agent:
|
||||
openclaw sandbox recreate --agent family
|
||||
```
|
||||
|
||||
### For a specific agent only
|
||||
|
||||
```bash
|
||||
# Update only one agent's containers
|
||||
openclaw sandbox recreate --agent alfred
|
||||
```
|
||||
|
||||
## Why is this needed?
|
||||
|
||||
**Problem:** When you update sandbox configuration:
|
||||
|
||||
- Existing runtimes continue running with old settings
|
||||
- Runtimes are only pruned after 24h of inactivity
|
||||
- Regularly-used agents keep old runtimes alive indefinitely
|
||||
|
||||
**Solution:** Use `openclaw sandbox recreate` to force removal of old runtimes. They'll be recreated automatically with current settings when next needed.
|
||||
|
||||
Tip: prefer `openclaw sandbox recreate` over manual backend-specific cleanup.
|
||||
It uses the Gateway’s runtime registry and avoids mismatches when scope/session keys change.
|
||||
|
||||
## Configuration
|
||||
|
||||
Sandbox settings live in `~/.openclaw/openclaw.json` under `agents.defaults.sandbox` (per-agent overrides go in `agents.list[].sandbox`):
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"sandbox": {
|
||||
"mode": "all", // off, non-main, all
|
||||
"backend": "docker", // docker, ssh, openshell
|
||||
"scope": "agent", // session, agent, shared
|
||||
"docker": {
|
||||
"image": "openclaw-sandbox:bookworm-slim",
|
||||
"containerPrefix": "openclaw-sbx-",
|
||||
// ... more Docker options
|
||||
},
|
||||
"prune": {
|
||||
"idleHours": 24, // Auto-prune after 24h idle
|
||||
"maxAgeDays": 7, // Auto-prune after 7 days
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- [Sandbox Documentation](/gateway/sandboxing)
|
||||
- [Agent Configuration](/concepts/agent-workspace)
|
||||
- [Doctor Command](/gateway/doctor) - Check sandbox setup
|
||||
197
openclaw/docs/cli/secrets.md
Normal file
197
openclaw/docs/cli/secrets.md
Normal file
|
|
@ -0,0 +1,197 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw secrets` (reload, audit, configure, apply)"
|
||||
read_when:
|
||||
- Re-resolving secret refs at runtime
|
||||
- Auditing plaintext residues and unresolved refs
|
||||
- Configuring SecretRefs and applying one-way scrub changes
|
||||
title: "secrets"
|
||||
---
|
||||
|
||||
# `openclaw secrets`
|
||||
|
||||
Use `openclaw secrets` to manage SecretRefs and keep the active runtime snapshot healthy.
|
||||
|
||||
Command roles:
|
||||
|
||||
- `reload`: gateway RPC (`secrets.reload`) that re-resolves refs and swaps runtime snapshot only on full success (no config writes).
|
||||
- `audit`: read-only scan of configuration/auth/generated-model stores and legacy residues for plaintext, unresolved refs, and precedence drift (exec refs are skipped unless `--allow-exec` is set).
|
||||
- `configure`: interactive planner for provider setup, target mapping, and preflight (TTY required).
|
||||
- `apply`: execute a saved plan (`--dry-run` for validation only; dry-run skips exec checks by default, and write mode rejects exec-containing plans unless `--allow-exec` is set), then scrub targeted plaintext residues.
|
||||
|
||||
Recommended operator loop:
|
||||
|
||||
```bash
|
||||
openclaw secrets audit --check
|
||||
openclaw secrets configure
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
|
||||
openclaw secrets audit --check
|
||||
openclaw secrets reload
|
||||
```
|
||||
|
||||
If your plan includes `exec` SecretRefs/providers, pass `--allow-exec` on both dry-run and write apply commands.
|
||||
|
||||
Exit code note for CI/gates:
|
||||
|
||||
- `audit --check` returns `1` on findings.
|
||||
- unresolved refs return `2`.
|
||||
|
||||
Related:
|
||||
|
||||
- Secrets guide: [Secrets Management](/gateway/secrets)
|
||||
- Credential surface: [SecretRef Credential Surface](/reference/secretref-credential-surface)
|
||||
- Security guide: [Security](/gateway/security)
|
||||
|
||||
## Reload runtime snapshot
|
||||
|
||||
Re-resolve secret refs and atomically swap runtime snapshot.
|
||||
|
||||
```bash
|
||||
openclaw secrets reload
|
||||
openclaw secrets reload --json
|
||||
openclaw secrets reload --url ws://127.0.0.1:18789 --token <token>
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Uses gateway RPC method `secrets.reload`.
|
||||
- If resolution fails, gateway keeps last-known-good snapshot and returns an error (no partial activation).
|
||||
- JSON response includes `warningCount`.
|
||||
|
||||
Options:
|
||||
|
||||
- `--url <url>`
|
||||
- `--token <token>`
|
||||
- `--timeout <ms>`
|
||||
- `--json`
|
||||
|
||||
## Audit
|
||||
|
||||
Scan OpenClaw state for:
|
||||
|
||||
- plaintext secret storage
|
||||
- unresolved refs
|
||||
- precedence drift (`auth-profiles.json` credentials shadowing `openclaw.json` refs)
|
||||
- generated `agents/*/agent/models.json` residues (provider `apiKey` values and sensitive provider headers)
|
||||
- legacy residues (legacy auth store entries, OAuth reminders)
|
||||
|
||||
Header residue note:
|
||||
|
||||
- Sensitive provider header detection is name-heuristic based (common auth/credential header names and fragments such as `authorization`, `x-api-key`, `token`, `secret`, `password`, and `credential`).
|
||||
|
||||
```bash
|
||||
openclaw secrets audit
|
||||
openclaw secrets audit --check
|
||||
openclaw secrets audit --json
|
||||
openclaw secrets audit --allow-exec
|
||||
```
|
||||
|
||||
Exit behavior:
|
||||
|
||||
- `--check` exits non-zero on findings.
|
||||
- unresolved refs exit with higher-priority non-zero code.
|
||||
|
||||
Report shape highlights:
|
||||
|
||||
- `status`: `clean | findings | unresolved`
|
||||
- `resolution`: `refsChecked`, `skippedExecRefs`, `resolvabilityComplete`
|
||||
- `summary`: `plaintextCount`, `unresolvedRefCount`, `shadowedRefCount`, `legacyResidueCount`
|
||||
- finding codes:
|
||||
- `PLAINTEXT_FOUND`
|
||||
- `REF_UNRESOLVED`
|
||||
- `REF_SHADOWED`
|
||||
- `LEGACY_RESIDUE`
|
||||
|
||||
## Configure (interactive helper)
|
||||
|
||||
Build provider and SecretRef changes interactively, run preflight, and optionally apply:
|
||||
|
||||
```bash
|
||||
openclaw secrets configure
|
||||
openclaw secrets configure --plan-out /tmp/openclaw-secrets-plan.json
|
||||
openclaw secrets configure --apply --yes
|
||||
openclaw secrets configure --providers-only
|
||||
openclaw secrets configure --skip-provider-setup
|
||||
openclaw secrets configure --agent ops
|
||||
openclaw secrets configure --json
|
||||
```
|
||||
|
||||
Flow:
|
||||
|
||||
- Provider setup first (`add/edit/remove` for `secrets.providers` aliases).
|
||||
- Credential mapping second (select fields and assign `{source, provider, id}` refs).
|
||||
- Preflight and optional apply last.
|
||||
|
||||
Flags:
|
||||
|
||||
- `--providers-only`: configure `secrets.providers` only, skip credential mapping.
|
||||
- `--skip-provider-setup`: skip provider setup and map credentials to existing providers.
|
||||
- `--agent <id>`: scope `auth-profiles.json` target discovery and writes to one agent store.
|
||||
- `--allow-exec`: allow exec SecretRef checks during preflight/apply (may execute provider commands).
|
||||
|
||||
Notes:
|
||||
|
||||
- Requires an interactive TTY.
|
||||
- You cannot combine `--providers-only` with `--skip-provider-setup`.
|
||||
- `configure` targets secret-bearing fields in `openclaw.json` plus `auth-profiles.json` for the selected agent scope.
|
||||
- `configure` supports creating new `auth-profiles.json` mappings directly in the picker flow.
|
||||
- Canonical supported surface: [SecretRef Credential Surface](/reference/secretref-credential-surface).
|
||||
- It performs preflight resolution before apply.
|
||||
- If preflight/apply includes exec refs, keep `--allow-exec` set for both steps.
|
||||
- Generated plans default to scrub options (`scrubEnv`, `scrubAuthProfilesForProviderTargets`, `scrubLegacyAuthJson` all enabled).
|
||||
- Apply path is one-way for scrubbed plaintext values.
|
||||
- Without `--apply`, CLI still prompts `Apply this plan now?` after preflight.
|
||||
- With `--apply` (and no `--yes`), CLI prompts an extra irreversible confirmation.
|
||||
- `--json` prints the plan + preflight report, but the command still requires an interactive TTY.
|
||||
|
||||
Exec provider safety note:
|
||||
|
||||
- Homebrew installs often expose symlinked binaries under `/opt/homebrew/bin/*`.
|
||||
- Set `allowSymlinkCommand: true` only when needed for trusted package-manager paths, and pair it with `trustedDirs` (for example `["/opt/homebrew"]`).
|
||||
- On Windows, if ACL verification is unavailable for a provider path, OpenClaw fails closed. For trusted paths only, set `allowInsecurePath: true` on that provider to bypass path security checks.
|
||||
|
||||
## Apply a saved plan
|
||||
|
||||
Apply or preflight a plan generated previously:
|
||||
|
||||
```bash
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
|
||||
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --json
|
||||
```
|
||||
|
||||
Exec behavior:
|
||||
|
||||
- `--dry-run` validates preflight without writing files.
|
||||
- exec SecretRef checks are skipped by default in dry-run.
|
||||
- write mode rejects plans that contain exec SecretRefs/providers unless `--allow-exec` is set.
|
||||
- Use `--allow-exec` to opt in to exec provider checks/execution in either mode.
|
||||
|
||||
Plan contract details (allowed target paths, validation rules, and failure semantics):
|
||||
|
||||
- [Secrets Apply Plan Contract](/gateway/secrets-plan-contract)
|
||||
|
||||
What `apply` may update:
|
||||
|
||||
- `openclaw.json` (SecretRef targets + provider upserts/deletes)
|
||||
- `auth-profiles.json` (provider-target scrubbing)
|
||||
- legacy `auth.json` residues
|
||||
- `~/.openclaw/.env` known secret keys whose values were migrated
|
||||
|
||||
## Why no rollback backups
|
||||
|
||||
`secrets apply` intentionally does not write rollback backups containing old plaintext values.
|
||||
|
||||
Safety comes from strict preflight + atomic-ish apply with best-effort in-memory restore on failure.
|
||||
|
||||
## Example
|
||||
|
||||
```bash
|
||||
openclaw secrets audit --check
|
||||
openclaw secrets configure
|
||||
openclaw secrets audit --check
|
||||
```
|
||||
|
||||
If `audit --check` still reports plaintext findings, update the remaining reported target paths and rerun audit.
|
||||
86
openclaw/docs/cli/security.md
Normal file
86
openclaw/docs/cli/security.md
Normal file
|
|
@ -0,0 +1,86 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw security` (audit and fix common security footguns)"
|
||||
read_when:
|
||||
- You want to run a quick security audit on config/state
|
||||
- You want to apply safe “fix” suggestions (permissions, tighten defaults)
|
||||
title: "security"
|
||||
---
|
||||
|
||||
# `openclaw security`
|
||||
|
||||
Security tools (audit + optional fixes).
|
||||
|
||||
Related:
|
||||
|
||||
- Security guide: [Security](/gateway/security)
|
||||
|
||||
## Audit
|
||||
|
||||
```bash
|
||||
openclaw security audit
|
||||
openclaw security audit --deep
|
||||
openclaw security audit --deep --password <password>
|
||||
openclaw security audit --deep --token <token>
|
||||
openclaw security audit --fix
|
||||
openclaw security audit --json
|
||||
```
|
||||
|
||||
The audit warns when multiple DM senders share the main session and recommends **secure DM mode**: `session.dmScope="per-channel-peer"` (or `per-account-channel-peer` for multi-account channels) for shared inboxes.
|
||||
This is for cooperative/shared inbox hardening. A single Gateway shared by mutually untrusted/adversarial operators is not a recommended setup; split trust boundaries with separate gateways (or separate OS users/hosts).
|
||||
It also emits `security.trust_model.multi_user_heuristic` when config suggests likely shared-user ingress (for example open DM/group policy, configured group targets, or wildcard sender rules), and reminds you that OpenClaw is a personal-assistant trust model by default.
|
||||
For intentional shared-user setups, the audit guidance is to sandbox all sessions, keep filesystem access workspace-scoped, and keep personal/private identities or credentials off that runtime.
|
||||
It also warns when small models (`<=300B`) are used without sandboxing and with web/browser tools enabled.
|
||||
For webhook ingress, it warns when `hooks.token` reuses the Gateway token, when `hooks.token` is short, when `hooks.path="/"`, when `hooks.defaultSessionKey` is unset, when `hooks.allowedAgentIds` is unrestricted, when request `sessionKey` overrides are enabled, and when overrides are enabled without `hooks.allowedSessionKeyPrefixes`.
|
||||
It also warns when sandbox Docker settings are configured while sandbox mode is off, when `gateway.nodes.denyCommands` uses ineffective pattern-like/unknown entries (exact node command-name matching only, not shell-text filtering), when `gateway.nodes.allowCommands` explicitly enables dangerous node commands, when global `tools.profile="minimal"` is overridden by agent tool profiles, when open groups expose runtime/filesystem tools without sandbox/workspace guards, and when installed extension plugin tools may be reachable under permissive tool policy.
|
||||
It also flags `gateway.allowRealIpFallback=true` (header-spoofing risk if proxies are misconfigured) and `discovery.mdns.mode="full"` (metadata leakage via mDNS TXT records).
|
||||
It also warns when sandbox browser uses Docker `bridge` network without `sandbox.browser.cdpSourceRange`.
|
||||
It also flags dangerous sandbox Docker network modes (including `host` and `container:*` namespace joins).
|
||||
It also warns when existing sandbox browser Docker containers have missing/stale hash labels (for example pre-migration containers missing `openclaw.browserConfigEpoch`) and recommends `openclaw sandbox recreate --browser --all`.
|
||||
It also warns when npm-based plugin/hook install records are unpinned, missing integrity metadata, or drift from currently installed package versions.
|
||||
It warns when channel allowlists rely on mutable names/emails/tags instead of stable IDs (Discord, Slack, Google Chat, Microsoft Teams, Mattermost, IRC scopes where applicable).
|
||||
It warns when `gateway.auth.mode="none"` leaves Gateway HTTP APIs reachable without a shared secret (`/tools/invoke` plus any enabled `/v1/*` endpoint).
|
||||
Settings prefixed with `dangerous`/`dangerously` are explicit break-glass operator overrides; enabling one is not, by itself, a security vulnerability report.
|
||||
For the complete dangerous-parameter inventory, see the "Insecure or dangerous flags summary" section in [Security](/gateway/security).
|
||||
|
||||
SecretRef behavior:
|
||||
|
||||
- `security audit` resolves supported SecretRefs in read-only mode for its targeted paths.
|
||||
- If a SecretRef is unavailable in the current command path, audit continues and reports `secretDiagnostics` (instead of crashing).
|
||||
- `--token` and `--password` only override deep-probe auth for that command invocation; they do not rewrite config or SecretRef mappings.
|
||||
|
||||
## JSON output
|
||||
|
||||
Use `--json` for CI/policy checks:
|
||||
|
||||
```bash
|
||||
openclaw security audit --json | jq '.summary'
|
||||
openclaw security audit --deep --json | jq '.findings[] | select(.severity=="critical") | .checkId'
|
||||
```
|
||||
|
||||
If `--fix` and `--json` are combined, output includes both fix actions and final report:
|
||||
|
||||
```bash
|
||||
openclaw security audit --fix --json | jq '{fix: .fix.ok, summary: .report.summary}'
|
||||
```
|
||||
|
||||
## What `--fix` changes
|
||||
|
||||
`--fix` applies safe, deterministic remediations:
|
||||
|
||||
- flips common `groupPolicy="open"` to `groupPolicy="allowlist"` (including account variants in supported channels)
|
||||
- when WhatsApp group policy flips to `allowlist`, seeds `groupAllowFrom` from
|
||||
the stored `allowFrom` file when that list exists and config does not already
|
||||
define `allowFrom`
|
||||
- sets `logging.redactSensitive` from `"off"` to `"tools"`
|
||||
- tightens permissions for state/config and common sensitive files
|
||||
(`credentials/*.json`, `auth-profiles.json`, `sessions.json`, session
|
||||
`*.jsonl`)
|
||||
- also tightens config include files referenced from `openclaw.json`
|
||||
- uses `chmod` on POSIX hosts and `icacls` resets on Windows
|
||||
|
||||
`--fix` does **not**:
|
||||
|
||||
- rotate tokens/passwords/API keys
|
||||
- disable tools (`gateway`, `cron`, `exec`, etc.)
|
||||
- change gateway bind/auth/network exposure choices
|
||||
- remove or rewrite plugins/skills
|
||||
113
openclaw/docs/cli/sessions.md
Normal file
113
openclaw/docs/cli/sessions.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw sessions` (list stored sessions + usage)"
|
||||
read_when:
|
||||
- You want to list stored sessions and see recent activity
|
||||
title: "sessions"
|
||||
---
|
||||
|
||||
# `openclaw sessions`
|
||||
|
||||
List stored conversation sessions.
|
||||
|
||||
```bash
|
||||
openclaw sessions
|
||||
openclaw sessions --agent work
|
||||
openclaw sessions --all-agents
|
||||
openclaw sessions --active 120
|
||||
openclaw sessions --verbose
|
||||
openclaw sessions --json
|
||||
```
|
||||
|
||||
Scope selection:
|
||||
|
||||
- default: configured default agent store
|
||||
- `--verbose`: verbose logging
|
||||
- `--agent <id>`: one configured agent store
|
||||
- `--all-agents`: aggregate all configured agent stores
|
||||
- `--store <path>`: explicit store path (cannot be combined with `--agent` or `--all-agents`)
|
||||
|
||||
`openclaw sessions --all-agents` reads configured agent stores. Gateway and ACP
|
||||
session discovery are broader: they also include disk-only stores found under
|
||||
the default `agents/` root or a templated `session.store` root. Those
|
||||
discovered stores must resolve to regular `sessions.json` files inside the
|
||||
agent root; symlinks and out-of-root paths are skipped.
|
||||
|
||||
JSON examples:
|
||||
|
||||
`openclaw sessions --all-agents --json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"path": null,
|
||||
"stores": [
|
||||
{ "agentId": "main", "path": "/home/user/.openclaw/agents/main/sessions/sessions.json" },
|
||||
{ "agentId": "work", "path": "/home/user/.openclaw/agents/work/sessions/sessions.json" }
|
||||
],
|
||||
"allAgents": true,
|
||||
"count": 2,
|
||||
"activeMinutes": null,
|
||||
"sessions": [
|
||||
{ "agentId": "main", "key": "agent:main:main", "model": "gpt-5" },
|
||||
{ "agentId": "work", "key": "agent:work:main", "model": "claude-opus-4-6" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Cleanup maintenance
|
||||
|
||||
Run maintenance now (instead of waiting for the next write cycle):
|
||||
|
||||
```bash
|
||||
openclaw sessions cleanup --dry-run
|
||||
openclaw sessions cleanup --agent work --dry-run
|
||||
openclaw sessions cleanup --all-agents --dry-run
|
||||
openclaw sessions cleanup --enforce
|
||||
openclaw sessions cleanup --enforce --active-key "agent:main:telegram:direct:123"
|
||||
openclaw sessions cleanup --json
|
||||
```
|
||||
|
||||
`openclaw sessions cleanup` uses `session.maintenance` settings from config:
|
||||
|
||||
- Scope note: `openclaw sessions cleanup` maintains session stores/transcripts only. It does not prune cron run logs (`cron/runs/<jobId>.jsonl`), which are managed by `cron.runLog.maxBytes` and `cron.runLog.keepLines` in [Cron configuration](/automation/cron-jobs#configuration) and explained in [Cron maintenance](/automation/cron-jobs#maintenance).
|
||||
|
||||
- `--dry-run`: preview how many entries would be pruned/capped without writing.
|
||||
- In text mode, dry-run prints a per-session action table (`Action`, `Key`, `Age`, `Model`, `Flags`) so you can see what would be kept vs removed.
|
||||
- `--enforce`: apply maintenance even when `session.maintenance.mode` is `warn`.
|
||||
- `--fix-missing`: remove entries whose transcript files are missing, even if they would not normally age/count out yet.
|
||||
- `--active-key <key>`: protect a specific active key from disk-budget eviction.
|
||||
- `--agent <id>`: run cleanup for one configured agent store.
|
||||
- `--all-agents`: run cleanup for all configured agent stores.
|
||||
- `--store <path>`: run against a specific `sessions.json` file.
|
||||
- `--json`: print a JSON summary. With `--all-agents`, output includes one summary per store.
|
||||
|
||||
`openclaw sessions cleanup --all-agents --dry-run --json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"allAgents": true,
|
||||
"mode": "warn",
|
||||
"dryRun": true,
|
||||
"stores": [
|
||||
{
|
||||
"agentId": "main",
|
||||
"storePath": "/home/user/.openclaw/agents/main/sessions/sessions.json",
|
||||
"beforeCount": 120,
|
||||
"afterCount": 80,
|
||||
"pruned": 40,
|
||||
"capped": 0
|
||||
},
|
||||
{
|
||||
"agentId": "work",
|
||||
"storePath": "/home/user/.openclaw/agents/work/sessions/sessions.json",
|
||||
"beforeCount": 18,
|
||||
"afterCount": 18,
|
||||
"pruned": 0,
|
||||
"capped": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
Related:
|
||||
|
||||
- Session config: [Configuration reference](/gateway/configuration-reference#session)
|
||||
45
openclaw/docs/cli/setup.md
Normal file
45
openclaw/docs/cli/setup.md
Normal file
|
|
@ -0,0 +1,45 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw setup` (initialize config + workspace)"
|
||||
read_when:
|
||||
- You’re doing first-run setup without full CLI onboarding
|
||||
- You want to set the default workspace path
|
||||
title: "setup"
|
||||
---
|
||||
|
||||
# `openclaw setup`
|
||||
|
||||
Initialize `~/.openclaw/openclaw.json` and the agent workspace.
|
||||
|
||||
Related:
|
||||
|
||||
- Getting started: [Getting started](/start/getting-started)
|
||||
- CLI onboarding: [Onboarding (CLI)](/start/wizard)
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw setup
|
||||
openclaw setup --workspace ~/.openclaw/workspace
|
||||
openclaw setup --wizard
|
||||
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--workspace <dir>`: agent workspace directory (stored as `agents.defaults.workspace`)
|
||||
- `--wizard`: run onboarding
|
||||
- `--non-interactive`: run onboarding without prompts
|
||||
- `--mode <local|remote>`: onboarding mode
|
||||
- `--remote-url <url>`: remote Gateway WebSocket URL
|
||||
- `--remote-token <token>`: remote Gateway token
|
||||
|
||||
To run onboarding via setup:
|
||||
|
||||
```bash
|
||||
openclaw setup --wizard
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Plain `openclaw setup` initializes config + workspace without the full onboarding flow.
|
||||
- Onboarding auto-runs when any onboarding flags are present (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).
|
||||
59
openclaw/docs/cli/skills.md
Normal file
59
openclaw/docs/cli/skills.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw skills` (search/install/update/list/info/check)"
|
||||
read_when:
|
||||
- You want to see which skills are available and ready to run
|
||||
- You want to search, install, or update skills from ClawHub
|
||||
- You want to debug missing binaries/env/config for skills
|
||||
title: "skills"
|
||||
---
|
||||
|
||||
# `openclaw skills`
|
||||
|
||||
Inspect local skills and install/update skills from ClawHub.
|
||||
|
||||
Related:
|
||||
|
||||
- Skills system: [Skills](/tools/skills)
|
||||
- Skills config: [Skills config](/tools/skills-config)
|
||||
- ClawHub installs: [ClawHub](/tools/clawhub)
|
||||
|
||||
## Commands
|
||||
|
||||
```bash
|
||||
openclaw skills search "calendar"
|
||||
openclaw skills search --limit 20 --json
|
||||
openclaw skills install <slug>
|
||||
openclaw skills install <slug> --version <version>
|
||||
openclaw skills install <slug> --force
|
||||
openclaw skills update <slug>
|
||||
openclaw skills update --all
|
||||
openclaw skills list
|
||||
openclaw skills list --eligible
|
||||
openclaw skills list --json
|
||||
openclaw skills list --verbose
|
||||
openclaw skills info <name>
|
||||
openclaw skills info <name> --json
|
||||
openclaw skills check
|
||||
openclaw skills check --json
|
||||
```
|
||||
|
||||
`search`/`install`/`update` use ClawHub directly and install into the active
|
||||
workspace `skills/` directory. `list`/`info`/`check` still inspect the local
|
||||
skills visible to the current workspace and config.
|
||||
|
||||
This CLI `install` command downloads skill folders from ClawHub. Gateway-backed
|
||||
skill dependency installs triggered from onboarding or Skills settings use the
|
||||
separate `skills.install` request path instead.
|
||||
|
||||
Notes:
|
||||
|
||||
- `search [query...]` accepts an optional query; omit it to browse the default
|
||||
ClawHub search feed.
|
||||
- `search --limit <n>` caps returned results.
|
||||
- `install --force` overwrites an existing workspace skill folder for the same
|
||||
slug.
|
||||
- `update --all` only updates tracked ClawHub installs in the active workspace.
|
||||
- `list` is the default action when no subcommand is provided.
|
||||
- `list`, `info`, and `check` write their rendered output to stdout. With
|
||||
`--json`, that means the machine-readable payload stays on stdout for pipes
|
||||
and scripts.
|
||||
35
openclaw/docs/cli/status.md
Normal file
35
openclaw/docs/cli/status.md
Normal file
|
|
@ -0,0 +1,35 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw status` (diagnostics, probes, usage snapshots)"
|
||||
read_when:
|
||||
- You want a quick diagnosis of channel health + recent session recipients
|
||||
- You want a pasteable “all” status for debugging
|
||||
title: "status"
|
||||
---
|
||||
|
||||
# `openclaw status`
|
||||
|
||||
Diagnostics for channels + sessions.
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
openclaw status --all
|
||||
openclaw status --deep
|
||||
openclaw status --usage
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
|
||||
- `--usage` prints normalized provider usage windows as `X% left`.
|
||||
- MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, so OpenClaw inverts them before display; count-based fields win when present. `model_remains` responses prefer the chat-model entry, derive the window label from timestamps when needed, and include the model name in the plan label.
|
||||
- When the current session snapshot is sparse, `/status` can backfill token and cache counters from the most recent transcript usage log. Existing nonzero live values still win over transcript fallback values.
|
||||
- Transcript fallback can also recover the active runtime model label when the live session entry is missing it. If that transcript model differs from the selected model, status resolves the context window against the recovered runtime model instead of the selected one.
|
||||
- For prompt-size accounting, transcript fallback prefers the larger prompt-oriented total when session metadata is missing or smaller, so custom-provider sessions do not collapse to `0` token displays.
|
||||
- Output includes per-agent session stores when multiple agents are configured.
|
||||
- Overview includes Gateway + node host service install/runtime status when available.
|
||||
- Overview includes update channel + git SHA (for source checkouts).
|
||||
- Update info surfaces in the Overview; if an update is available, status prints a hint to run `openclaw update` (see [Updating](/install/updating)).
|
||||
- Read-only status surfaces (`status`, `status --json`, `status --all`) resolve supported SecretRefs for their targeted config paths when possible.
|
||||
- If a supported channel SecretRef is configured but unavailable in the current command path, status stays read-only and reports degraded output instead of crashing. Human output shows warnings such as “configured token unavailable in this command path”, and JSON output includes `secretDiagnostics`.
|
||||
- When command-local SecretRef resolution succeeds, status prefers the resolved snapshot and clears transient “secret unavailable” channel markers from the final output.
|
||||
- `status --all` includes a Secrets overview row and a diagnosis section that summarizes secret diagnostics (truncated for readability) without stopping report generation.
|
||||
71
openclaw/docs/cli/system.md
Normal file
71
openclaw/docs/cli/system.md
Normal file
|
|
@ -0,0 +1,71 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw system` (system events, heartbeat, presence)"
|
||||
read_when:
|
||||
- You want to enqueue a system event without creating a cron job
|
||||
- You need to enable or disable heartbeats
|
||||
- You want to inspect system presence entries
|
||||
title: "system"
|
||||
---
|
||||
|
||||
# `openclaw system`
|
||||
|
||||
System-level helpers for the Gateway: enqueue system events, control heartbeats,
|
||||
and view presence.
|
||||
|
||||
All `system` subcommands use Gateway RPC and accept the shared client flags:
|
||||
|
||||
- `--url <url>`
|
||||
- `--token <token>`
|
||||
- `--timeout <ms>`
|
||||
- `--expect-final`
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw system event --text "Check for urgent follow-ups" --mode now
|
||||
openclaw system event --text "Check for urgent follow-ups" --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"
|
||||
openclaw system heartbeat enable
|
||||
openclaw system heartbeat last
|
||||
openclaw system presence
|
||||
```
|
||||
|
||||
## `system event`
|
||||
|
||||
Enqueue a system event on the **main** session. The next heartbeat will inject
|
||||
it as a `System:` line in the prompt. Use `--mode now` to trigger the heartbeat
|
||||
immediately; `next-heartbeat` waits for the next scheduled tick.
|
||||
|
||||
Flags:
|
||||
|
||||
- `--text <text>`: required system event text.
|
||||
- `--mode <mode>`: `now` or `next-heartbeat` (default).
|
||||
- `--json`: machine-readable output.
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
|
||||
|
||||
## `system heartbeat last|enable|disable`
|
||||
|
||||
Heartbeat controls:
|
||||
|
||||
- `last`: show the last heartbeat event.
|
||||
- `enable`: turn heartbeats back on (use this if they were disabled).
|
||||
- `disable`: pause heartbeats.
|
||||
|
||||
Flags:
|
||||
|
||||
- `--json`: machine-readable output.
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
|
||||
|
||||
## `system presence`
|
||||
|
||||
List the current system presence entries the Gateway knows about (nodes,
|
||||
instances, and similar status lines).
|
||||
|
||||
Flags:
|
||||
|
||||
- `--json`: machine-readable output.
|
||||
- `--url`, `--token`, `--timeout`, `--expect-final`: shared Gateway RPC flags.
|
||||
|
||||
## Notes
|
||||
|
||||
- Requires a running Gateway reachable by your current config (local or remote).
|
||||
- System events are ephemeral and not persisted across restarts.
|
||||
30
openclaw/docs/cli/tui.md
Normal file
30
openclaw/docs/cli/tui.md
Normal file
|
|
@ -0,0 +1,30 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw tui` (terminal UI connected to the Gateway)"
|
||||
read_when:
|
||||
- You want a terminal UI for the Gateway (remote-friendly)
|
||||
- You want to pass url/token/session from scripts
|
||||
title: "tui"
|
||||
---
|
||||
|
||||
# `openclaw tui`
|
||||
|
||||
Open the terminal UI connected to the Gateway.
|
||||
|
||||
Related:
|
||||
|
||||
- TUI guide: [TUI](/web/tui)
|
||||
|
||||
Notes:
|
||||
|
||||
- `tui` resolves configured gateway auth SecretRefs for token/password auth when possible (`env`/`file`/`exec` providers).
|
||||
- When launched from inside a configured agent workspace directory, TUI auto-selects that agent for the session key default (unless `--session` is explicitly `agent:<id>:...`).
|
||||
|
||||
## Examples
|
||||
|
||||
```bash
|
||||
openclaw tui
|
||||
openclaw tui --url ws://127.0.0.1:18789 --token <token>
|
||||
openclaw tui --session main --deliver
|
||||
# when run inside an agent workspace, infers that agent automatically
|
||||
openclaw tui --session bugfix
|
||||
```
|
||||
39
openclaw/docs/cli/uninstall.md
Normal file
39
openclaw/docs/cli/uninstall.md
Normal file
|
|
@ -0,0 +1,39 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw uninstall` (remove gateway service + local data)"
|
||||
read_when:
|
||||
- You want to remove the gateway service and/or local state
|
||||
- You want a dry-run first
|
||||
title: "uninstall"
|
||||
---
|
||||
|
||||
# `openclaw uninstall`
|
||||
|
||||
Uninstall the gateway service + local data (CLI remains).
|
||||
|
||||
Options:
|
||||
|
||||
- `--service`: remove the gateway service
|
||||
- `--state`: remove state and config
|
||||
- `--workspace`: remove workspace directories
|
||||
- `--app`: remove the macOS app
|
||||
- `--all`: remove service, state, workspace, and app
|
||||
- `--yes`: skip confirmation prompts
|
||||
- `--non-interactive`: disable prompts; requires `--yes`
|
||||
- `--dry-run`: print actions without removing files
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw backup create
|
||||
openclaw uninstall
|
||||
openclaw uninstall --service --yes --non-interactive
|
||||
openclaw uninstall --state --workspace --yes --non-interactive
|
||||
openclaw uninstall --all --yes
|
||||
openclaw uninstall --dry-run
|
||||
```
|
||||
|
||||
Notes:
|
||||
|
||||
- Run `openclaw backup create` first if you want a restorable snapshot before removing state or workspaces.
|
||||
- `--all` is shorthand for removing service, state, workspace, and app together.
|
||||
- `--non-interactive` requires `--yes`.
|
||||
115
openclaw/docs/cli/update.md
Normal file
115
openclaw/docs/cli/update.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw update` (safe-ish source update + gateway auto-restart)"
|
||||
read_when:
|
||||
- You want to update a source checkout safely
|
||||
- You need to understand `--update` shorthand behavior
|
||||
title: "update"
|
||||
---
|
||||
|
||||
# `openclaw update`
|
||||
|
||||
Safely update OpenClaw and switch between stable/beta/dev channels.
|
||||
|
||||
If you installed via **npm/pnpm/bun** (global install, no git metadata),
|
||||
updates happen via the package-manager flow in [Updating](/install/updating).
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
openclaw update
|
||||
openclaw update status
|
||||
openclaw update wizard
|
||||
openclaw update --channel beta
|
||||
openclaw update --channel dev
|
||||
openclaw update --tag beta
|
||||
openclaw update --tag main
|
||||
openclaw update --dry-run
|
||||
openclaw update --no-restart
|
||||
openclaw update --yes
|
||||
openclaw update --json
|
||||
openclaw --update
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
- `--no-restart`: skip restarting the Gateway service after a successful update.
|
||||
- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
|
||||
- `--tag <dist-tag|version|spec>`: override the package target for this update only. For package installs, `main` maps to `github:openclaw/openclaw#main`.
|
||||
- `--dry-run`: preview planned update actions (channel/tag/target/restart flow) without writing config, installing, syncing plugins, or restarting.
|
||||
- `--json`: print machine-readable `UpdateRunResult` JSON.
|
||||
- `--timeout <seconds>`: per-step timeout (default is 1200s).
|
||||
- `--yes`: skip confirmation prompts (for example downgrade confirmation)
|
||||
|
||||
Note: downgrades require confirmation because older versions can break configuration.
|
||||
|
||||
## `update status`
|
||||
|
||||
Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
|
||||
|
||||
```bash
|
||||
openclaw update status
|
||||
openclaw update status --json
|
||||
openclaw update status --timeout 10
|
||||
```
|
||||
|
||||
Options:
|
||||
|
||||
- `--json`: print machine-readable status JSON.
|
||||
- `--timeout <seconds>`: timeout for checks (default is 3s).
|
||||
|
||||
## `update wizard`
|
||||
|
||||
Interactive flow to pick an update channel and confirm whether to restart the Gateway
|
||||
after updating (default is to restart). If you select `dev` without a git checkout, it
|
||||
offers to create one.
|
||||
|
||||
Options:
|
||||
|
||||
- `--timeout <seconds>`: timeout for each update step (default `1200`)
|
||||
|
||||
## What it does
|
||||
|
||||
When you switch channels explicitly (`--channel ...`), OpenClaw also keeps the
|
||||
install method aligned:
|
||||
|
||||
- `dev` → ensures a git checkout (default: `~/openclaw`, override with `OPENCLAW_GIT_DIR`),
|
||||
updates it, and installs the global CLI from that checkout.
|
||||
- `stable` → installs from npm using `latest`.
|
||||
- `beta` → prefers npm dist-tag `beta`, but falls back to `latest` when beta is
|
||||
missing or older than the current stable release.
|
||||
|
||||
The Gateway core auto-updater (when enabled via config) reuses this same update path.
|
||||
|
||||
## Git checkout flow
|
||||
|
||||
Channels:
|
||||
|
||||
- `stable`: checkout the latest non-beta tag, then build + doctor.
|
||||
- `beta`: prefer the latest `-beta` tag, but fall back to the latest stable tag
|
||||
when beta is missing or older.
|
||||
- `dev`: checkout `main`, then fetch + rebase.
|
||||
|
||||
High-level:
|
||||
|
||||
1. Requires a clean worktree (no uncommitted changes).
|
||||
2. Switches to the selected channel (tag or branch).
|
||||
3. Fetches upstream (dev only).
|
||||
4. Dev only: preflight lint + TypeScript build in a temp worktree; if the tip fails, walks back up to 10 commits to find the newest clean build.
|
||||
5. Rebases onto the selected commit (dev only).
|
||||
6. Installs deps with the repo package manager. For pnpm checkouts, the updater bootstraps `pnpm` on demand (via `corepack` first, then a temporary `npm install pnpm@10` fallback) instead of running `npm run build` inside a pnpm workspace.
|
||||
7. Builds + builds the Control UI.
|
||||
8. Runs `openclaw doctor` as the final “safe update” check.
|
||||
9. Syncs plugins to the active channel (dev uses bundled extensions; stable/beta uses npm) and updates npm-installed plugins.
|
||||
|
||||
If pnpm bootstrap still fails, the updater now stops early with a package-manager-specific error instead of trying `npm run build` inside the checkout.
|
||||
|
||||
## `--update` shorthand
|
||||
|
||||
`openclaw --update` rewrites to `openclaw update` (useful for shells and launcher scripts).
|
||||
|
||||
## See also
|
||||
|
||||
- `openclaw doctor` (offers to run update first on git checkouts)
|
||||
- [Development channels](/install/development-channels)
|
||||
- [Updating](/install/updating)
|
||||
- [CLI reference](/cli)
|
||||
34
openclaw/docs/cli/voicecall.md
Normal file
34
openclaw/docs/cli/voicecall.md
Normal file
|
|
@ -0,0 +1,34 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw voicecall` (voice-call plugin command surface)"
|
||||
read_when:
|
||||
- You use the voice-call plugin and want the CLI entry points
|
||||
- You want quick examples for `voicecall call|continue|status|tail|expose`
|
||||
title: "voicecall"
|
||||
---
|
||||
|
||||
# `openclaw voicecall`
|
||||
|
||||
`voicecall` is a plugin-provided command. It only appears if the voice-call plugin is installed and enabled.
|
||||
|
||||
Primary doc:
|
||||
|
||||
- Voice-call plugin: [Voice Call](/plugins/voice-call)
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw voicecall status --call-id <id>
|
||||
openclaw voicecall call --to "+15555550123" --message "Hello" --mode notify
|
||||
openclaw voicecall continue --call-id <id> --message "Any questions?"
|
||||
openclaw voicecall end --call-id <id>
|
||||
```
|
||||
|
||||
## Exposing webhooks (Tailscale)
|
||||
|
||||
```bash
|
||||
openclaw voicecall expose --mode serve
|
||||
openclaw voicecall expose --mode funnel
|
||||
openclaw voicecall expose --mode off
|
||||
```
|
||||
|
||||
Security note: only expose the webhook endpoint to networks you trust. Prefer Tailscale Serve over Funnel when possible.
|
||||
91
openclaw/docs/cli/webhooks.md
Normal file
91
openclaw/docs/cli/webhooks.md
Normal file
|
|
@ -0,0 +1,91 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw webhooks` (webhook helpers + Gmail Pub/Sub)"
|
||||
read_when:
|
||||
- You want to wire Gmail Pub/Sub events into OpenClaw
|
||||
- You want webhook helper commands
|
||||
title: "webhooks"
|
||||
---
|
||||
|
||||
# `openclaw webhooks`
|
||||
|
||||
Webhook helpers and integrations (Gmail Pub/Sub, webhook helpers).
|
||||
|
||||
Related:
|
||||
|
||||
- Webhooks: [Webhooks](/automation/cron-jobs#webhooks)
|
||||
- Gmail Pub/Sub: [Gmail Pub/Sub](/automation/cron-jobs#gmail-pubsub-integration)
|
||||
|
||||
## Gmail
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail setup --account you@example.com
|
||||
openclaw webhooks gmail run
|
||||
```
|
||||
|
||||
### `webhooks gmail setup`
|
||||
|
||||
Configure Gmail watch, Pub/Sub, and OpenClaw webhook delivery.
|
||||
|
||||
Required:
|
||||
|
||||
- `--account <email>`
|
||||
|
||||
Options:
|
||||
|
||||
- `--project <id>`
|
||||
- `--topic <name>`
|
||||
- `--subscription <name>`
|
||||
- `--label <label>`
|
||||
- `--hook-url <url>`
|
||||
- `--hook-token <token>`
|
||||
- `--push-token <token>`
|
||||
- `--bind <host>`
|
||||
- `--port <port>`
|
||||
- `--path <path>`
|
||||
- `--include-body`
|
||||
- `--max-bytes <n>`
|
||||
- `--renew-minutes <n>`
|
||||
- `--tailscale <funnel|serve|off>`
|
||||
- `--tailscale-path <path>`
|
||||
- `--tailscale-target <target>`
|
||||
- `--push-endpoint <url>`
|
||||
- `--json`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail setup --account you@example.com
|
||||
openclaw webhooks gmail setup --account you@example.com --project my-gcp-project --json
|
||||
openclaw webhooks gmail setup --account you@example.com --hook-url https://gateway.example.com/hooks/gmail
|
||||
```
|
||||
|
||||
### `webhooks gmail run`
|
||||
|
||||
Run `gog watch serve` plus the watch auto-renew loop.
|
||||
|
||||
Options:
|
||||
|
||||
- `--account <email>`
|
||||
- `--topic <topic>`
|
||||
- `--subscription <name>`
|
||||
- `--label <label>`
|
||||
- `--hook-url <url>`
|
||||
- `--hook-token <token>`
|
||||
- `--push-token <token>`
|
||||
- `--bind <host>`
|
||||
- `--port <port>`
|
||||
- `--path <path>`
|
||||
- `--include-body`
|
||||
- `--max-bytes <n>`
|
||||
- `--renew-minutes <n>`
|
||||
- `--tailscale <funnel|serve|off>`
|
||||
- `--tailscale-path <path>`
|
||||
- `--tailscale-target <target>`
|
||||
|
||||
Example:
|
||||
|
||||
```bash
|
||||
openclaw webhooks gmail run --account you@example.com
|
||||
```
|
||||
|
||||
See [Gmail Pub/Sub documentation](/automation/cron-jobs#gmail-pubsub-integration) for the end-to-end setup flow and operational details.
|
||||
214
openclaw/docs/cli/wiki.md
Normal file
214
openclaw/docs/cli/wiki.md
Normal file
|
|
@ -0,0 +1,214 @@
|
|||
---
|
||||
summary: "CLI reference for `openclaw wiki` (memory-wiki vault status, search, compile, lint, apply, bridge, and Obsidian helpers)"
|
||||
read_when:
|
||||
- You want to use the memory-wiki CLI
|
||||
- You are documenting or changing `openclaw wiki`
|
||||
title: "wiki"
|
||||
---
|
||||
|
||||
# `openclaw wiki`
|
||||
|
||||
Inspect and maintain the `memory-wiki` vault.
|
||||
|
||||
Provided by the bundled `memory-wiki` plugin.
|
||||
|
||||
Related:
|
||||
|
||||
- [Memory Wiki plugin](/plugins/memory-wiki)
|
||||
- [Memory Overview](/concepts/memory)
|
||||
- [CLI: memory](/cli/memory)
|
||||
|
||||
## What it is for
|
||||
|
||||
Use `openclaw wiki` when you want a compiled knowledge vault with:
|
||||
|
||||
- wiki-native search and page reads
|
||||
- provenance-rich syntheses
|
||||
- contradiction and freshness reports
|
||||
- bridge imports from the active memory plugin
|
||||
- optional Obsidian CLI helpers
|
||||
|
||||
## Common commands
|
||||
|
||||
```bash
|
||||
openclaw wiki status
|
||||
openclaw wiki doctor
|
||||
openclaw wiki init
|
||||
openclaw wiki ingest ./notes/alpha.md
|
||||
openclaw wiki compile
|
||||
openclaw wiki lint
|
||||
openclaw wiki search "alpha"
|
||||
openclaw wiki get entity.alpha --from 1 --lines 80
|
||||
|
||||
openclaw wiki apply synthesis "Alpha Summary" \
|
||||
--body "Short synthesis body" \
|
||||
--source-id source.alpha
|
||||
|
||||
openclaw wiki apply metadata entity.alpha \
|
||||
--source-id source.alpha \
|
||||
--status review \
|
||||
--question "Still active?"
|
||||
|
||||
openclaw wiki bridge import
|
||||
openclaw wiki unsafe-local import
|
||||
|
||||
openclaw wiki obsidian status
|
||||
openclaw wiki obsidian search "alpha"
|
||||
openclaw wiki obsidian open syntheses/alpha-summary.md
|
||||
openclaw wiki obsidian command workspace:quick-switcher
|
||||
openclaw wiki obsidian daily
|
||||
```
|
||||
|
||||
## Commands
|
||||
|
||||
### `wiki status`
|
||||
|
||||
Inspect current vault mode, health, and Obsidian CLI availability.
|
||||
|
||||
Use this first when you are unsure whether the vault is initialized, bridge mode
|
||||
is healthy, or Obsidian integration is available.
|
||||
|
||||
### `wiki doctor`
|
||||
|
||||
Run wiki health checks and surface configuration or vault problems.
|
||||
|
||||
Typical issues include:
|
||||
|
||||
- bridge mode enabled without public memory artifacts
|
||||
- invalid or missing vault layout
|
||||
- missing external Obsidian CLI when Obsidian mode is expected
|
||||
|
||||
### `wiki init`
|
||||
|
||||
Create the wiki vault layout and starter pages.
|
||||
|
||||
This initializes the root structure, including top-level indexes and cache
|
||||
directories.
|
||||
|
||||
### `wiki ingest <path-or-url>`
|
||||
|
||||
Import content into the wiki source layer.
|
||||
|
||||
Notes:
|
||||
|
||||
- URL ingest is controlled by `ingest.allowUrlIngest`
|
||||
- imported source pages keep provenance in frontmatter
|
||||
- auto-compile can run after ingest when enabled
|
||||
|
||||
### `wiki compile`
|
||||
|
||||
Rebuild indexes, related blocks, dashboards, and compiled digests.
|
||||
|
||||
This writes stable machine-facing artifacts under:
|
||||
|
||||
- `.openclaw-wiki/cache/agent-digest.json`
|
||||
- `.openclaw-wiki/cache/claims.jsonl`
|
||||
|
||||
If `render.createDashboards` is enabled, compile also refreshes report pages.
|
||||
|
||||
### `wiki lint`
|
||||
|
||||
Lint the vault and report:
|
||||
|
||||
- structural issues
|
||||
- provenance gaps
|
||||
- contradictions
|
||||
- open questions
|
||||
- low-confidence pages/claims
|
||||
- stale pages/claims
|
||||
|
||||
Run this after meaningful wiki updates.
|
||||
|
||||
### `wiki search <query>`
|
||||
|
||||
Search wiki content.
|
||||
|
||||
Behavior depends on config:
|
||||
|
||||
- `search.backend`: `shared` or `local`
|
||||
- `search.corpus`: `wiki`, `memory`, or `all`
|
||||
|
||||
Use `wiki search` when you want wiki-specific ranking or provenance details.
|
||||
For one broad shared recall pass, prefer `openclaw memory search` when the
|
||||
active memory plugin exposes shared search.
|
||||
|
||||
### `wiki get <lookup>`
|
||||
|
||||
Read a wiki page by id or relative path.
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
openclaw wiki get entity.alpha
|
||||
openclaw wiki get syntheses/alpha-summary.md --from 1 --lines 80
|
||||
```
|
||||
|
||||
### `wiki apply`
|
||||
|
||||
Apply narrow mutations without freeform page surgery.
|
||||
|
||||
Supported flows include:
|
||||
|
||||
- create/update a synthesis page
|
||||
- update page metadata
|
||||
- attach source ids
|
||||
- add questions
|
||||
- add contradictions
|
||||
- update confidence/status
|
||||
- write structured claims
|
||||
|
||||
This command exists so the wiki can evolve safely without manually editing
|
||||
managed blocks.
|
||||
|
||||
### `wiki bridge import`
|
||||
|
||||
Import public memory artifacts from the active memory plugin into bridge-backed
|
||||
source pages.
|
||||
|
||||
Use this in `bridge` mode when you want the latest exported memory artifacts
|
||||
pulled into the wiki vault.
|
||||
|
||||
### `wiki unsafe-local import`
|
||||
|
||||
Import from explicitly configured local paths in `unsafe-local` mode.
|
||||
|
||||
This is intentionally experimental and same-machine only.
|
||||
|
||||
### `wiki obsidian ...`
|
||||
|
||||
Obsidian helper commands for vaults running in Obsidian-friendly mode.
|
||||
|
||||
Subcommands:
|
||||
|
||||
- `status`
|
||||
- `search`
|
||||
- `open`
|
||||
- `command`
|
||||
- `daily`
|
||||
|
||||
These require the official `obsidian` CLI on `PATH` when
|
||||
`obsidian.useOfficialCli` is enabled.
|
||||
|
||||
## Practical usage guidance
|
||||
|
||||
- Use `wiki search` + `wiki get` when provenance and page identity matter.
|
||||
- Use `wiki apply` instead of hand-editing managed generated sections.
|
||||
- Use `wiki lint` before trusting contradictory or low-confidence content.
|
||||
- Use `wiki compile` after bulk imports or source changes when you want fresh
|
||||
dashboards and compiled digests immediately.
|
||||
- Use `wiki bridge import` when bridge mode depends on newly exported memory
|
||||
artifacts.
|
||||
|
||||
## Configuration tie-ins
|
||||
|
||||
`openclaw wiki` behavior is shaped by:
|
||||
|
||||
- `plugins.entries.memory-wiki.config.vaultMode`
|
||||
- `plugins.entries.memory-wiki.config.search.backend`
|
||||
- `plugins.entries.memory-wiki.config.search.corpus`
|
||||
- `plugins.entries.memory-wiki.config.bridge.*`
|
||||
- `plugins.entries.memory-wiki.config.obsidian.*`
|
||||
- `plugins.entries.memory-wiki.config.render.*`
|
||||
- `plugins.entries.memory-wiki.config.context.includeCompiledDigestPrompt`
|
||||
|
||||
See [Memory Wiki plugin](/plugins/memory-wiki) for the full config model.
|
||||
Loading…
Add table
Add a link
Reference in a new issue