Openclaw

OpenClaw Maintenance Skill

OpenClaw is a self-hosted, open-source (MIT) gateway that routes AI agents across WhatsApp, Telegram, Discord, Slack, iMessage, Signal, and 15+ other channels simultaneously. It runs on macOS, Linux, or Windows.

Reference Files

Quick Reference

Key Paths

Essential Commands

openclaw status                    # Overall status
openclaw gateway status            # Gateway daemon status
openclaw gateway status --deep     # Deep scan including system services
openclaw doctor                    # Diagnose config/service issues
openclaw doctor --fix              # Auto-fix safe issues
openclaw logs --follow             # Tail gateway logs
openclaw channels status --probe   # Channel health check
openclaw security audit            # Security posture check
openclaw security audit --fix      # Auto-fix security issues
openclaw update                    # Self-update
openclaw dashboard                 # Open Control UI in browser
openclaw tui                       # Terminal UI (interactive REPL)
openclaw agent                     # Direct agent interaction via CLI
openclaw health                    # Health check
openclaw usage                     # Usage tracking
openclaw config validate           # Validate config file
openclaw config file               # Print active config path
openclaw sessions cleanup          # Session disk cleanup
openclaw agents bindings           # Agent-channel bindings
openclaw agents bind               # Bind agent to account
openclaw agents unbind             # Unbind agent
openclaw update --dry-run          # Preview update
openclaw system presence           # View connected clients/nodes
openclaw system heartbeat last     # Last heartbeat info
openclaw system heartbeat now      # Trigger heartbeat immediately
openclaw memory search <query>     # CLI memory search
openclaw docs <query>              # Search OpenClaw docs
openclaw tasks list                # List background/detached task runs
openclaw tasks show <id>           # Show specific task details
openclaw tasks cancel <id>         # Cancel a running task
openclaw tasks audit               # Identify problematic task runs
openclaw agent --message "..."     # Run single agent turn (scripted/testing)
openclaw nodes pending             # List pending pairing requests
openclaw nodes approve <id>        # Approve node pairing
openclaw nodes status              # Show all paired nodes
openclaw health --json             # Full health snapshot (JSON)
openclaw message send --media <p>  # Send media message

Default Gateway

• Bind: 127.0.0.1:18789 (loopback)
• Dashboard: http://127.0.0.1:18789/
• Protocol: WebSocket (JSON text frames)

Core Workflow

Diagnosing Issues

Always follow this command ladder:

1. openclaw status — quick overview 2. openclaw gateway status — daemon running? RPC probe ok? 3. openclaw logs --follow — watch for errors 4. openclaw doctor — config/service diagnostics 5. openclaw channels status --probe — per-channel health

Starting / Restarting Gateway

# Foreground with verbose logging
openclaw gateway --port 18789 --verbose

# Force-kill existing listener then start
openclaw gateway --force

# Service management (launchd on macOS, systemd on Linux)
openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart

Configuration

Edit config via any method:

# Interactive wizard
openclaw onboard                    # Full setup
openclaw configure                  # Config wizard

# CLI one-liners
openclaw config get <path>          # Read value
openclaw config set <path> <value>  # Set value (JSON5 or raw string)
openclaw config unset <path>        # Remove value

# Direct edit
# Edit ~/.openclaw/openclaw.json (JSON5 format)
# Gateway hot-reloads on save (if gateway.reload.mode != "off")

Minimal config example:

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Channel Setup

For detailed per-channel setup, see references/channels.md. For per-channel troubleshooting (failure signatures, setup walkthroughs), see references/channel_troubleshooting.md. For plugins adding new channels (Matrix, Nostr, MS Teams, etc.), see references/plugins.md.

Quick channel add:

# Interactive wizard
openclaw channels add

# Non-interactive
openclaw channels add --channel telegram --account default --name "My Bot" --token $BOT_TOKEN
openclaw channels login --channel whatsapp     # QR pairing for WhatsApp
openclaw channels status --probe               # Verify

Model Provider Setup

For detailed provider setup, see references/providers.md.

# Set default model
openclaw models set anthropic/claude-sonnet-4-5

# List available models
openclaw models list --all

# Check auth/token status
openclaw models status --probe

# Add auth interactively
openclaw models auth add

Config example:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
    },
  },
}

Multi-Agent Routing

For detailed multi-agent config, see references/multi_agent.md.

openclaw agents add <id>                # Create agent
openclaw agents list --bindings         # Show agent-channel bindings
openclaw agents delete <id>             # Remove agent

Nodes (iOS / Android / macOS / Headless)

For detailed node setup, see references/nodes.md.

openclaw nodes status                   # List connected nodes
openclaw nodes describe --node <id>     # Node capabilities
openclaw devices list                   # Pending device approvals
openclaw devices approve <requestId>    # Approve a device
openclaw node run --host <host> --port 18789  # Start headless node host

Security

For detailed security hardening, see references/security.md. For secrets management (SecretRef, vault integration), see references/secrets.md. For sandboxing (Docker isolation for tools), see references/sandboxing.md. For full config field reference, see references/config_reference.md. For remote access (SSH, Tailscale, VPN), see references/remote_access.md.

openclaw security audit                 # Check posture
openclaw security audit --deep          # Live gateway probe
openclaw security audit --fix           # Auto-fix safe issues
openclaw secrets reload                 # Re-resolve secret refs
openclaw secrets audit                  # Scan for plaintext leaks

Update / Uninstall

For detailed installation, updating, rollback, and migration guide, see references/install.md.

# Install (recommended)
curl -fsSL https://openclaw.ai/install.sh | bash

# Update
openclaw update                    # Self-update command
# Or: npm install -g openclaw@latest
openclaw doctor                    # Run after update to apply migrations

# Uninstall
openclaw uninstall

Tools Reference

For detailed per-tool documentation, see references/tools.md.

For specific tools, see:

• references/exec.md — Exec tool deep-dive
• references/exec_approvals.md — Exec approvals and allowlists
• references/browser.md — Browser automation deep-dive
• references/web_tools.md — Web search/fetch with multiple providers
• references/lobster.md — Lobster workflow runtime
• references/llm_task.md — LLM Task for structured JSON output
• references/openprose.md — OpenProse multi-agent programs
• references/plugins.md — Plugin system (install, author, distribute)
• references/skills.md — Skills system (load, config, ClawHub)

For ACP agents (Codex, Claude Code, Gemini CLI, etc.), see references/acp_agents.md. For Diffs plugin and Firecrawl anti-bot fallback, see references/diffs_firecrawl.md. For chat slash commands (/new, /model, /acp, etc.), see references/slash_commands.md. For thinking levels (/think, /verbose, /reasoning), see references/thinking.md. For polls (Telegram, WhatsApp, Discord, MS Teams), see references/polls.md. For Talk Mode and Voice Wake, see references/voice.md. For Gateway architecture and wire protocol, see references/architecture.md. For agent runtime and loop details, see references/agent_runtime.md. For command queue system, see references/queue.md. For model failover and OAuth, see references/model_failover.md. For ClawHub skill registry, see references/clawhub.md. For presence and discovery, see references/presence_discovery.md. For streaming and chunking, see references/streaming.md. For Gateway internals (network model, lock, health, doctor, logging), see references/gateway_internals.md. For heartbeat system, see references/heartbeat.md. For Bonjour/mDNS discovery details, see references/bonjour.md. For Gateway node pairing, see references/pairing.md. For Terminal UI (TUI), see references/tui.md. For media (camera, images, audio), see references/media.md. For channel routing and session keys, see references/channel_routing.md.

Tool profiles: minimal, coding, messaging, full (default).

Tool groups (for allow/deny):

• group:runtime — exec, bash, process
• group:fs — read, write, edit, apply_patch
• group:sessions — sessions_list/history/send/spawn, session_status
• group:memory — memory_search, memory_get
• group:web — web_search, web_fetch
• group:ui — browser, canvas
• group:automation — cron, gateway
• group:messaging — message
• group:nodes — nodes
• group:openclaw — all built-in OpenClaw tools (excludes provider plugins)

Common Failure Signatures

Environment Variables

OpenClaw Agent Skill 🦞

English | 中文文档

一套完整的 Agent Skill，用于安装、配置、运维和排障 OpenClaw —— 一个自托管的多通道 AI Agent 网关。

这是什么？

这是一个专为 AI 编程助手（如 Claude + Antigravity）设计的 Agent Skill。安装后，AI 助手会获得 OpenClaw 的深度知识，能帮你完成：

• 安装与升级 — 安装、升级或迁移 OpenClaw
• 配置管理 — 编辑 openclaw.json、设置模型、管理密钥
• 频道管理 — 配置 WhatsApp、Telegram、Discord、Slack、iMessage 等 20+ 频道
• Gateway 运维 — 启动、停止、重启、健康检查、远程访问
• 多 Agent 路由 — 配置多个 Agent，隔离工作区和会话
• ACP Agents — 启动外部 AI 运行时（Codex、Claude Code、Gemini CLI，14+ 运行时）
• 浏览器自动化 — 多 Profile 浏览器控制、Chrome MCP 现有会话、快照/Refs
• 插件系统 — 能力模型、Context Engine 插件、SDK、Hook API
• 自动化 — 定时任务、Standing Orders、后台任务、Webhooks、Hooks
• 安全加固 — 审计、访问控制、受信代理、事件响应
• 故障排查 — 诊断和修复 CLI 及 Gateway 的常见错误

Skill 结构

OpenClaw-Skill/
├── SKILL.md                     # 主入口（核心工作流、命令速查、故障签名表）
└── references/
    ├── architecture.md          # Gateway 架构、WebSocket 协议、配对、不变量
    ├── agent_runtime.md         # Agent 运行时、引导文件、Agent Loop、Hooks、超时
    ├── bonjour.md               # Bonjour/mDNS：TXT 键、广域 DNS-SD、调试
    ├── channel_routing.md       # 频道路由、Session Key、Mattermost、BlueBubbles
    ├── channels.md              # 20+ 频道配置指南（WhatsApp、Telegram、Discord 等）
    ├── clawhub.md               # ClawHub 公共 Skill 注册中心、CLI 命令
    ├── gateway_internals.md     # 网络模型、Gateway 锁、健康检查、Doctor、日志、后台执行
    ├── gateway_ops.md           # Gateway 运维、服务管理
    ├── heartbeat.md             # 心跳：配置、投递、可见性、HEARTBEAT.md
    ├── media.md                 # 媒体：相机拍摄、图像、音频/语音笔记、转录
    ├── memory.md                # 记忆系统、向量搜索、混合 BM25、QMD 后端
    ├── model_failover.md        # 模型故障转移、OAuth、认证配置、冷却策略
    ├── multi_agent.md           # 多 Agent 路由、Bindings、Agent 配置
    ├── pairing.md               # Gateway 配对：节点审批、CLI、API、自动审批
    ├── polls.md                 # 投票功能（Telegram、WhatsApp、Discord、MS Teams）
    ├── presence_discovery.md    # Presence 系统、发现机制（Bonjour/Tailscale）
    ├── providers.md             # 35+ 模型提供商（Anthropic、OpenAI、Google、Ollama 等）
    ├── queue.md                 # 命令队列：steer/followup/collect 模式
    ├── security.md              # 认证、访问控制、加固基线
    ├── streaming.md             # 块流式传输、分块、合并、预览模式
    ├── thinking.md              # 思考级别、详细模式指令、推理可见性
    ├── tui.md                   # TUI：快捷键、斜杠命令、选择器、本地 Shell
    ├── voice.md                 # Talk Mode（语音交互）+ Voice Wake（唤醒词）
    └── ... (共 51 个参考文件)

共计约 6,000+ 行结构化参考文档，覆盖 OpenClaw 所有核心功能。

安装方法

Antigravity（Claude）用户

将 Skill 文件夹复制到 Antigravity 的 skills 目录：

# 克隆仓库
git clone https://github.com/win4r/OpenClaw-Skill.git

# 复制到 skills 目录
cp -r OpenClaw-Skill ~/.gemini/antigravity/skills/openclaw

安装后，当你提到 OpenClaw 相关任务时，Skill 会自动触发。

其他 AI 助手

SKILL.md 和 references/ 中的结构化文档可以适配到任何支持 Skill/知识注入的 AI 助手。

使用示例

安装后，自然语言提问即可：

常用命令速查

# 状态与健康检查
openclaw status                    # 总体状态
openclaw gateway status            # Gateway 守护进程状态
openclaw doctor                    # 诊断问题
openclaw channels status --probe   # 频道健康检查

# Gateway 管理
openclaw gateway install           # 安装为系统服务
openclaw gateway start/stop/restart

# 配置管理
openclaw config get <路径>          # 读取配置值
openclaw config set <路径> <值>     # 设置配置值
openclaw configure                 # 交互式向导

# 安全
openclaw security audit            # 检查安全状况
openclaw security audit --fix      # 自动修复问题
openclaw secrets reload            # 重新加载密钥引用

# 频道
openclaw channels add              # 添加频道（向导模式）
openclaw channels login            # WhatsApp QR 配对
openclaw channels list             # 显示已配置频道

# 模型
openclaw models set <模型>          # 设置默认模型
openclaw models status --probe     # 检查认证状态

文档来源

本 Skill 基于 OpenClaw 官方文档 构建，涵盖：

• 安装
• Gateway 架构
• Agent 运行时
• Agent Loop
• 配置
• 频道
• 模型提供商
• 模型故障转移与 OAuth
• 工具
• 思考级别
• 命令队列
• 流式传输与分块
• 记忆与向量搜索
• ClawHub 注册中心
• 多 Agent 路由
• Talk Mode 与 Voice Wake
• 投票功能
• Presence 与发现机制
• ACP Agents
• 安全
• 故障排查
• CLI 参考

许可证

本 Skill 免费提供给 AI 助手使用。OpenClaw 本身采用 MIT 许可证。

贡献

欢迎 Issue 和 PR！如果 OpenClaw 发布了新功能或变更，请随时更新 references 文件。

OpenClaw Agent Skill 🦞

中文文档 | English

A comprehensive Agent Skill for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway.

What is This?

This is an Agent Skill designed for AI coding assistants (like Claude with Antigravity). Once installed, the AI assistant gains deep knowledge of OpenClaw and can help you with:

• Installation & Updates — Install, upgrade, or migrate OpenClaw
• Configuration — Edit openclaw.json, set up models, manage secrets
• Channel Management — Set up WhatsApp, Telegram, Discord, Slack, iMessage, and 15+ other channels
• Gateway Operations — Start, stop, restart, health check, remote access
• Multi-Agent Routing — Configure multiple agents with isolated workspaces and sessions
• ACP Agents — Spawn external AI runtimes (Codex, Claude Code, Gemini CLI, 14+ harnesses)
• Browser Automation — Multi-profile browser control, Chrome MCP existing-session, snapshots/refs
• Plugin System — Capability model, context engine plugins, SDK, hook API
• Automation — Cron jobs, standing orders, background tasks, webhooks, hooks
• Security Hardening — Audit, lock down access, manage tokens, trusted proxy, incident response
• Troubleshooting — Diagnose and fix common errors from CLI and Gateway

Skill Structure

OpenClaw-Skill/
├── SKILL.md                     # Main entry (core workflows, commands, troubleshooting)
└── references/              
    ├── architecture.md          # Gateway architecture, wire protocol, pairing, invariants
    ├── agent_runtime.md         # Agent runtime, bootstrap, agent loop, hooks, timeouts
    ├── bonjour.md               # Bonjour/mDNS: TXT keys, wide-area DNS-SD, debugging
    ├── channel_routing.md       # Channel routing, session keys, Mattermost, BlueBubbles
    ├── channels.md              # 20+ channel setup guides (WhatsApp, Telegram, Discord, etc.)
    ├── clawhub.md               # ClawHub public skill registry, CLI commands
    ├── gateway_internals.md     # Network model, lock, health, doctor, logging, background exec
    ├── gateway_ops.md           # Gateway operations, service management
    ├── heartbeat.md             # Heartbeat: config, delivery, visibility, HEARTBEAT.md
    ├── media.md                 # Media: camera capture, images, audio/voice notes, transcription
    ├── memory.md                # Memory system, vector search, hybrid BM25, QMD backend
    ├── model_failover.md        # Model failover, OAuth, auth profiles, cooldowns
    ├── multi_agent.md           # Multi-agent routing, bindings, per-agent config
    ├── pairing.md               # Gateway pairing: node approval, CLI, API, auto-approval
    ├── polls.md                 # Polls (Telegram, WhatsApp, Discord, MS Teams)
    ├── presence_discovery.md    # Presence system, discovery (Bonjour/Tailscale)
    ├── providers.md             # 35+ model providers (Anthropic, OpenAI, Google, Ollama, etc.)
    ├── queue.md                 # Command queue: steer/followup/collect modes
    ├── security.md              # Auth, access control, hardening baseline
    ├── streaming.md             # Block streaming, chunking, coalescing, preview modes
    ├── thinking.md              # Thinking levels, verbose directives, reasoning visibility
    ├── tui.md                   # TUI: keyboard shortcuts, slash commands, pickers, local shell
    ├── voice.md                 # Talk Mode (voice interaction) + Voice Wake (wake words)
    └── ... (51 reference files total)

Total: ~6,000+ lines of structured reference covering all core OpenClaw functionality.

Installation

For Antigravity (Claude)

Copy the skill folder to your Antigravity skills directory:

# Clone this repo
git clone https://github.com/win4r/OpenClaw-Skill.git

# Copy to your skills directory
cp -r OpenClaw-Skill ~/.gemini/antigravity/skills/openclaw

The skill will be automatically detected and triggered when you ask about OpenClaw-related tasks.

For Other AI Assistants

The SKILL.md and references/ files contain structured documentation that can be adapted for any AI assistant that supports skill/knowledge injection.

Usage Examples

Once installed, just ask naturally:

Key Commands Quick Reference

# Status & Health
openclaw status                    # Overall status
openclaw gateway status            # Gateway daemon status
openclaw doctor                    # Diagnose issues
openclaw channels status --probe   # Channel health

# Gateway Management
openclaw gateway install           # Install as system service
openclaw gateway start/stop/restart

# Configuration
openclaw config get <path>         # Read config value
openclaw config set <path> <value> # Set config value
openclaw configure                 # Interactive wizard

# Security
openclaw security audit            # Check security posture
openclaw security audit --fix      # Auto-fix issues
openclaw secrets reload            # Reload secret refs

# Channels
openclaw channels add              # Add channel (wizard)
openclaw channels login            # WhatsApp QR pairing
openclaw channels list             # Show configured channels

# Models
openclaw models set <model>        # Set default model
openclaw models status --probe     # Check auth status

Documentation Source

This skill is built from the official OpenClaw Documentation, covering:

• Install
• Gateway Architecture
• Agent Runtime
• Agent Loop
• Configuration
• Channels
• Model Providers
• Model Failover & OAuth
• Tools
• Thinking Levels
• Command Queue
• Streaming & Chunking
• Memory & Vector Search
• ClawHub Registry
• Multi-Agent Routing
• Talk Mode & Voice Wake
• Polls
• Presence & Discovery
• ACP Agents
• Sandboxing
• Automation (Cron, Webhooks, Hooks)
• Background Tasks
• Standing Orders
• Context Engine
• Plugin Architecture
• Browser Tool
• Agent Send
• Security
• Formal Verification
• Troubleshooting
• CLI Reference

License

This skill is provided as-is for use with AI assistants. OpenClaw itself is MIT licensed.

Contributing

Issues and PRs welcome! If OpenClaw releases new features or changes, feel free to update the reference files accordingly.

OpenClaw ACP Agents Reference

Table of Contents

• Overview
• ACP vs Sub-Agents
• Fast Operator Flow
• ACP Controls
• ACP Command Cookbook
• Thread-Bound Sessions
• Session Target Resolution
• Supported Harnesses
• Required Config
• Plugin Setup
• Permission Configuration
• Troubleshooting
• ACP CLI Bridge

Overview

ACP (Agent Communication Protocol) agents allow OpenClaw to spawn and manage external AI agent runtimes (Codex, Claude Code, Gemini CLI, OpenCode, etc.) as persistent or one-shot sessions, with thread-bound routing and live controls.

Natural-language triggers:

• "Start a persistent Codex session in a thread and keep it focused."
• "Run this as a one-shot Claude Code ACP session and summarize the result."
• "Use Gemini CLI for this task in a thread, then keep follow-ups in that same thread."

ACP vs Sub-Agents

Fast Operator Flow

/acp spawn codex --mode persistent --thread auto   # 1. Spawn session
# Work in the bound thread...
/acp status                                          # 2. Check state
/acp model <provider/model>                          # 3. Tune model
/acp permissions <profile>                           # 4. Set permissions
/acp timeout <seconds>                               # 5. Set timeout
/acp steer tighten logging and continue              # 6. Nudge without replacing context
/acp cancel                                          # 7. Stop current turn
/acp close                                           # 8. Close session + remove bindings

ACP Controls

Runtime Options Mapping

ACP Command Cookbook

/acp spawn codex --mode persistent --thread auto --cwd /repo
/acp cancel agent:codex:acp:<uuid>
/acp steer --session support inbox prioritize failing tests
/acp close
/acp status
/acp set-mode plan
/acp set model openai/gpt-5.4
/acp cwd /Users/user/Projects/repo
/acp permissions strict
/acp timeout 120
/acp model anthropic/claude-opus-4-6
/acp reset-options
/acp sessions
/acp doctor
/acp install

Thread-Bound Sessions

Thread binding works across channels:

1. OpenClaw binds a thread to a target ACP session 2. Follow-up messages in that thread route to the bound ACP session 3. ACP output is delivered back to the same thread 4. Unfocus/close/archive/idle-timeout or max-age expiry removes the binding

Spawn thread modes (--thread):

Required Config for Thread Binding

{
  session: {
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
  },
  channels: {
    discord: {
      threadBindings: {
        enabled: true,
        spawnAcpSessions: true,
      },
    },
  },
}

Session Target Resolution

When a /acp command refers to a target session, resolution order:

1. Explicit target argument (or --session for /acp steer)

• tries key → UUID-shaped session id → label

2. Current thread binding (if thread is bound to ACP session) 3. Current requester session fallback

Supported Harnesses

The acpx backend supports these built-in harness aliases:

Custom agents can be added with --agent <command>.

Session Resumption

Use resumeSessionId to continue a previous ACP session. The agent replays its conversation history via session/load, picking up with full context:

{
  "task": "Continue from where we left off",
  "runtime": "acp",
  "agentId": "codex",
  "resumeSessionId": "previous-session-uuid"
}

Sandbox Limitations

ACP sessions currently run on the host runtime, not inside the OpenClaw sandbox. Sandboxed sessions cannot spawn ACP sessions — use runtime="subagent" instead.

Required Config

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "codex",
    allowedAgents: ["pi", "claude", "codex", "opencode", "gemini", "kimi"],
    maxConcurrentSessions: 8,
    stream: {
      coalesceIdleMs: 300,
      maxChunkChars: 1200,
    },
    runtime: {
      ttlMinutes: 120,
    },
  },
}

Plugin Setup

Install acpx Backend

# Quick install
openclaw plugins install acpx

# From registry (full name)
openclaw plugins install @openclaw/acpx
openclaw config set plugins.entries.acpx.enabled true

# From source
openclaw plugins install ./extensions/acpx

# Verify
/acp doctor

Permission Configuration

permissionMode

nonInteractivePermissions

Configure

openclaw config set plugins.entries.acpx.config.permissionMode approve-all
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail

Recommended for non-interactive: permissionMode=approve-reads + nonInteractivePermissions=fail.

Troubleshooting

---

ACP CLI Bridge (openclaw acp)

Source: https://docs.openclaw.ai/cli/acp

The openclaw acp command runs an ACP-compatible stdio bridge, letting external IDE agents (Codex, Claude Code, Zed, etc.) send prompts into an OpenClaw Gateway session.

Usage

# Default (local Gateway)
openclaw acp

# Remote Gateway
openclaw acp --url wss://gateway-host:18789 --token <token>

# Remote Gateway (token from file — preferred for process safety)
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 Mode)

# Default
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

Security Notes (Auto-Approval)

• 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).
• Unknown/non-core tool names, out-of-scope reads, and dangerous tools always require explicit prompt approval.
• Server-provided toolCall.kind is treated as untrusted metadata (not an authorization source).

Selecting Agents

openclaw acp --session agent:main:main      # Main agent, main session
openclaw acp --session agent:design:main    # Design agent
openclaw acp --session agent:qa:bug-123     # QA agent, specific issue

Session Mapping

JSON meta equivalent:

{
  "_meta": {
    "sessionKey": "agent:main:main",
    "sessionLabel": "support inbox",
    "resetSession": true
  }
}

Options

openclaw acp Options

acp client Options

Auth Resolution

• `--token`/`--password` can be visible in local process listings — prefer --token-file/--password-file or env vars.
• Local mode: env (OPENCLAW_GATEWAY_*) → gateway.auth.* → gateway.remote.* fallback
• Remote mode: gateway.remote.* with env/config fallback per remote precedence rules
• `--url` is override-safe: does not reuse implicit config/env credentials; pass explicit --token/--password

Environment

• ACP runtime backend processes receive OPENCLAW_SHELL=acp.
• openclaw acp client sets OPENCLAW_SHELL=acp-client on the spawned bridge process.

Use from acpx (Codex, Claude, Other ACP Clients)

# 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."

acpx Config (~/.acpx/config.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"
    }
  }
}

Zed Editor Setup

Add to ~/.config/zed/settings.json:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": ["acp"],
      "env": {}
    }
  }
}

Remote with specific agent:

{
  "agent_servers": {
    "OpenClaw ACP": {
      "type": "custom",
      "command": "openclaw",
      "args": [
        "acp",
        "--url", "wss://gateway-host:18789",
        "--token", "<token>",
        "--session", "agent:design:main"
      ],
      "env": {}
    }
  }
}

How to Use This

1. Ensure the Gateway is running (local or remote). 2. Configure the Gateway target (config or flags):

   openclaw config set gateway.remote.url wss://gateway-host:18789
   openclaw config set gateway.remote.token <token>

3. Point your IDE to run openclaw acp over stdio.

Agent Runtime & Agent Loop

Sources:

- https://docs.openclaw.ai/concepts/agent

- https://docs.openclaw.ai/concepts/agent-loop

- https://docs.openclaw.ai/concepts/agent-workspace

Agent Runtime

Workspace (Required)

• Set via agents.defaults.workspace or cwd during openclaw setup.
• Config: ~/.openclaw/openclaw.json.
• Sandbox: agents.defaults.sandbox / agents.defaults.sandbox.workspaceRoot.

Bootstrap Files (Injected)

Up to eight files auto-injected into agents.defaults.workspace:

• Created by openclaw setup.
• Blank files are skipped. Large files are trimmed and truncated with a marker.
• BOOTSTRAP.md is deleted post-completion; won't recreate unless the entire bootstrap file set is removed.
• Skip bootstrap: { agent: { skipBootstrap: true } }.
• Truncation limits: 20,000 chars per file, 150,000 total by default.

Skills

• Bundled (shipped with the install)
• Managed/local: ~/.openclaw/skills
• Workspace: <workspace>/skills

pi-mono Integration

• No pi-coding agent runtime.
• No ~/.pi/agent or <workspace>/.pi settings are consulted.

Sessions

• Stored at: ~/.openclaw/agents/<agentId>/sessions/<SessionId>.jsonl

Steering While Streaming

• steer / followup / collect modes.
• Config: agents.defaults.blockStreamingDefault: "off", agents.defaults.blockStreamingBreak, agents.defaults.blockStreamingChunk, agents.defaults.blockStreamingCoalesce.
• Per-channel: *.blockStreaming: true.

Model Refs

• Config at agents.defaults.model / agents.defaults.models.
• Use provider/model format. If model ID itself contains / (OpenRouter-style), include the provider prefix (e.g. openrouter/moonshotai/kimi-k2).
• If provider is omitted, OpenClaw treats input as an alias or model for the default provider.

Minimal Configuration

• agents.defaults.workspace
• channels.whatsapp.allowFrom (strongly recommended)

---

Agent Loop

Entry Points

• Gateway RPC: agent and agent.wait.
• CLI: agent command.

How It Works (High-Level)

1. agent RPC validates params, resolves session (sessionKey/sessionId), persists session metadata, returns { runId, acceptedAt } immediately. 2. agentCommand runs the agent:

• Resolves model + thinking/verbose defaults
• Loads skills snapshot
• Calls runEmbeddedPiAgent (pi-agent-core runtime)
• Emits lifecycle end/error if the embedded loop does not emit one

3. runEmbeddedPiAgent:

• Serializes runs via per-session + global queues
• Resolves model + auth profile and builds the pi session
• Subscribes to pi events and streams assistant/tool deltas
• Enforces timeout → aborts run if exceeded
• Returns payloads + usage metadata

4. subscribeEmbeddedPiSession bridges pi-agent-core events to OpenClaw agent stream:

• tool events ⇒ stream: "tool"
• assistant deltas ⇒ stream: "assistant"
• lifecycle events ⇒ stream: "lifecycle" (phase: "start" | "end" | "error")

5. agent.wait uses waitForAgentJob:

• Waits for lifecycle end/error for runId
• Returns { status: ok|error|timeout, startedAt, endedAt, error? }

Queueing + Concurrency

• Runs are serialized per session key (session lane) and optionally through a global lane.
• Prevents tool/session races and keeps session history consistent.
• Messaging channels can choose queue modes (collect/steer/followup).

Prompt Assembly + System Prompt

• Built from OpenClaw's base prompt, skills prompt, bootstrap context, and per-run overrides.
• Model-specific limits and compaction reserve tokens are enforced.

Hook Points

Internal Hooks (Gateway Hooks)

• agent:bootstrap: runs while building bootstrap files before the system prompt is finalized.
• Command hooks: /new, /reset, /stop, and other command events.

Plugin Hooks (Agent + Gateway Lifecycle)

Streaming + Partial Replies

• Assistant deltas streamed from pi-agent-core as assistant events.
• Block streaming on text_end or message_end.

Reply Shaping + Suppression

• NO_REPLY is treated as a silent token, filtered from outgoing payloads.
• Messaging tool duplicates are removed from the final payload list.
• If no renderable payloads remain and a tool errored, a fallback tool error reply is emitted.

Timeouts

• agent.wait default: 30s (just the wait). timeoutMs param overrides.
• Agent runtime: agents.defaults.timeoutSeconds default 600s; enforced in runEmbeddedPiAgent abort timer.

Event Streams

Where Things Can End Early

• Agent timeout (abort)
• AbortSignal (cancel)
• Gateway disconnect or RPC timeout
• agent.wait timeout (wait-only, does not stop agent)

---

Context Engine

Controls how OpenClaw builds model context for each run. "Context" = everything the model receives, constrained by the model's token limit.

What Counts Toward Context

Everything sent to the model: system prompts, conversation history, tool calls/results, attachments, compaction summaries, and provider wrappers.

System Prompt Components

Rebuilt each run: tool lists, skills metadata, workspace location, time info, and injected bootstrap files. Skills listed compactly with descriptions; full instructions load on-demand.

Inspection Commands

Lifecycle Points

1. Ingest — stores/indexes new messages 2. Assemble — returns ordered messages fitting token budget 3. Compact — summarizes older history when context fills 4. After turn — persists state, triggers background compaction

Pluggable Context Engines

Plugins can register custom context engines:

api.registerContextEngine("my-engine", () => ({
  info: { id: "my-engine", name: "My Context Engine", ownsCompaction: true },
  async ingest({ sessionId, message }) { ... },
  async assemble({ sessionId, messages, tokenBudget }) { ... },
  async compact({ sessionId, force }) { ... },
}));

Configuration

{
  plugins: {
    slots: { contextEngine: "legacy" }, // or plugin name
  },
}

---

Session Pruning

Removes aged tool outputs before LLM requests. Benefits Anthropic prompt caching.

• Mode: cache-ttl — only toolResult messages pruned; user/assistant messages preserved
• Defaults: TTL 5 min, keepLastAssistants 3, softTrimRatio 0.3, hardClearRatio 0.5

Separate from compaction (can use both). Pruning is per-request and does not persist changes.

Gateway Architecture

Source: https://docs.openclaw.ai/concepts/architecture

Overview

• A single long-lived Gateway owns all messaging surfaces (WhatsApp via Baileys, Telegram via grammY, Slack, Discord, Signal, iMessage, WebChat).
• Control-plane clients (macOS app, CLI, web UI, automations) connect to the Gateway over WebSocket on the configured bind host (default 127.0.0.1:18789).
• Nodes (macOS/iOS/Android/headless) also connect over WebSocket, but declare role: node with explicit caps/commands.
• One Gateway per host; it is the only place that opens a WhatsApp session.
• Canvas host served by Gateway HTTP server under:
• /__openclaw__/canvas/ — agent-editable HTML/CSS/JS
• /__openclaw__/a2ui/ — A2UI host
• Same port as Gateway (default 18789).

Components and Flows

Gateway (Daemon)

• Maintains provider connections.
• Exposes a typed WS API (requests, responses, server-push events).
• Validates inbound frames against JSON Schema.
• Emits events: agent, chat, presence, health, heartbeat, cron.

Clients (macOS App / CLI / Web Admin)

• One WS connection per client.
• Send requests: health, status, send, agent, system-presence.
• Subscribe to events: tick, agent, presence, shutdown.

Nodes (macOS / iOS / Android / Headless)

• Connect to the same WS server with role: node.
• Provide device identity in connect; pairing is device-based and approval lives in the device pairing store.
• Expose commands: canvas.*, camera.*, screen.record, location.get.

WebChat

• Static UI that uses the Gateway WS API for chat history and sends.
• In remote setups, connects through the same SSH/Tailscale tunnel as other clients.

Wire Protocol (Summary)

• Transport: WebSocket, text frames with JSON payloads.
• First frame must be connect.
• After handshake:
• Requests: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
• Events: {type:"event", event, payload, seq?, stateVersion?}
• If OPENCLAW_GATEWAY_TOKEN (or --token) is set, connect.params.auth.token must match or the socket closes.
• Idempotency keys are required for side-effecting methods (send, agent) to safely retry; the server keeps a short-lived dedupe cache.
• Nodes must include role: "node" plus caps/commands/permissions in connect.

Pairing + Local Trust

• All WS clients (operators + nodes) include a device identity on connect.
• New device IDs require pairing approval; the Gateway issues a device token for subsequent connects.
• Local connects (loopback or the gateway host's own tailnet address) can be auto-approved to keep same-host UX smooth.
• All connects must sign the connect.challenge nonce.
• Signature payload v3 also binds platform + deviceFamily; the gateway pins paired metadata on reconnect and requires repair pairing for metadata changes.
• Non-local connects still require explicit approval.
• Gateway auth (gateway.auth.*) still applies to all connections, local or remote.

Protocol Typing and Codegen

• TypeBox schemas define the protocol.
• JSON Schema is generated from those schemas.
• Swift models are generated from the JSON Schema.

Remote Access

• Preferred: Tailscale or VPN.
• Alternative: SSH tunnel — ssh -N -L 18789:127.0.0.1:18789 user@host
• The same handshake + auth token apply over the tunnel.
• TLS + optional pinning can be enabled for WS in remote setups.

Operations Snapshot

• Start: openclaw gateway (foreground, logs to stdout).
• Health: health over WS (also included in hello-ok).
• Supervision: launchd/systemd for auto-restart.

Invariants

• Exactly one Gateway controls a single Baileys session per host.
• Handshake is mandatory; any non-JSON or non-connect first frame is a hard close.
• Events are not replayed; clients must refresh on gaps.

OpenClaw Automation Reference (Cron Jobs, Webhooks, Gmail Pub/Sub)

Table of Contents

• Cron Jobs
• Webhooks
• Gmail Pub/Sub
• Standing Orders
• Hooks

---

Cron Jobs

Cron runs inside the Gateway (not inside the model). Jobs persist under ~/.openclaw/cron/jobs.json.

Quick Start

# One-shot reminder
openclaw cron add \
  --name "Reminder" \
  --at "2026-02-01T16:00:00Z" \
  --session main \
  --system-event "Reminder: check the docs" \
  --wake now \
  --delete-after-run

# Recurring isolated job with announce
openclaw cron add \
  --name "Morning brief" \
  --cron "0 7 * * *" \
  --tz "America/Los_Angeles" \
  --session isolated \
  --message "Summarize overnight updates." \
  --announce \
  --channel slack \
  --to "channel:C1234567890"

# Management
openclaw cron list
openclaw cron run <job-id>
openclaw cron runs --id <job-id>

Concepts

Jobs

Each job has:

• Schedule (when it runs)
• Payload (what it does)
• Delivery mode (optional): announce, webhook, or none
• Agent binding (optional): agentId — run under a specific agent

Schedules

Options: --stagger 30s to set stagger window, --exact to force staggerMs = 0.

Execution Modes

Main session jobs: payload.kind = "systemEvent". Wake options: "now" (immediate) or "next-heartbeat".

Isolated jobs: Each run starts a fresh sessionId. Prompt prefixed with [cron:<jobId> <job name>].

Payload Shapes

• systemEvent: main-session only, routed through heartbeat
• agentTurn: isolated only, runs a dedicated agent turn with message, optional model/thinking/timeoutSeconds

Delivery

Delivery fields:

• delivery.channel: whatsapp / telegram / discord / slack / mattermost / signal / imessage / last
• delivery.to: channel-specific target or webhook URL
• delivery.bestEffort: avoid failing if announce delivery fails

Telegram topics: Use delivery.to: "-1001234567890:topic:123" format.

Model & Thinking Overrides

Override priority: Job payload → Hook-specific defaults → Agent config default.

• model: provider/model string or alias
• thinking: off, minimal, low, medium, high, xhigh

Advanced Features

Lightweight Bootstrap

Use lightContext: true in the payload to skip workspace bootstrap file injection — useful for simple chores that don't need full agent context.

Tool Allowlists

openclaw cron add --name "Job" --tools exec,read     # Only allow exec and read
openclaw cron edit <jobId> --clear-tools              # Remove tool restriction

Agent Pinning

openclaw cron add --name "Job" --agent ops            # Run under specific agent
openclaw cron edit <jobId> --agent main                # Change agent binding

Stagger Control

Top-of-hour cron expressions get a deterministic stagger window (up to 5 minutes) to reduce load spikes. Fixed-hour expressions like 0 7 * * * remain exact.

openclaw cron add --name "Job" --cron "0 * * * *" --stagger 30s
openclaw cron edit <jobId> --exact                     # Force staggerMs = 0

Custom Persistent Sessions

Use a named session to maintain context across runs:

{
  "name": "Project monitor",
  "schedule": { "kind": "every", "everyMs": 300000 },
  "sessionTarget": "session:project-alpha-monitor",
  "payload": {
    "kind": "agentTurn",
    "message": "Check project status and update the running log."
  }
}

Retry Policy

One-shot jobs:

• Transient errors (rate limit, overloaded, network, 5xx): retry up to 3 times with exponential backoff (30s, 1m, 5m)
• Permanent errors (auth, validation): disable immediately

Recurring jobs:

• Any error: exponential backoff (30s, 1m, 5m, 15m, 60m) before next run
• Job stays enabled; backoff resets after successful execution

Configuration

{
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/jobs.json",
    maxConcurrentRuns: 1,
    retry: {
      maxAttempts: 3,
      backoffMs: [60000, 120000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "server_error"],
    },
    webhookToken: "your-token",
    sessionRetention: "24h",          // Isolation run-session pruning
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

Disable cron: cron.enabled: false or env OPENCLAW_SKIP_CRON=1.

Cron Storage & Pruning

• Job store: ~/.openclaw/cron/jobs.json (Gateway-managed, manual edits only safe when Gateway stopped)
• Run history: ~/.openclaw/cron/runs/<jobId>.jsonl (auto-pruned by runLog.maxBytes / runLog.keepLines)
• Isolation session pruning: default 24h retention for cron:<jobId>:run:<uuid> sessions. Set cron.sessionRetention: false to disable.

Troubleshooting

---

Webhooks

HTTP endpoints exposed by the Gateway for external triggers.

Enable

{
  gateway: {
    webhooks: { enabled: true },
  },
}

Auth

Webhooks require gateway.auth.token or gateway.auth.password. Pass via Authorization: Bearer <token> header.

Endpoints

POST /hooks/wake

Trigger a wake/heartbeat cycle.

curl -X POST http://127.0.0.1:18789/hooks/wake \
  -H "Authorization: Bearer $TOKEN"

POST /hooks/agent

Send a prompt to the agent, run a dedicated turn.

curl -X POST http://127.0.0.1:18789/hooks/agent \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"message": "Check server status"}'

Options: model, thinking, agentId, sessionKey, delivery.

POST /hooks/<name> (mapped)

Custom-named webhook endpoints configured in gateway.webhooks.map.

Session Key Policy

By default, each webhook call gets a fresh hook:<uuid> session key. Override with sessionKey in the request body.

Responses

Returns { status: "ok", sessionId: "..." } on success, or error details.

Security

• Always use auth tokens
• Restrict network exposure (bind to loopback or use Tailscale)
• Webhooks inherit the agent's tool permissions

---

Gmail Pub/Sub

Connect Gmail inbox notifications to OpenClaw via Google Cloud Pub/Sub.

Prerequisites

• Google Cloud project with Gmail API + Pub/Sub enabled
• Service account or OAuth credentials
• A Pub/Sub topic and push subscription

Setup

# Wizard (recommended)
openclaw webhooks gmail setup

# Manual one-time setup
# 1. Create GCP Pub/Sub topic
# 2. Grant Gmail publish rights
# 3. Configure OpenClaw

Start the Watch

openclaw webhooks gmail watch

Run the Push Handler

Configure the push subscription to POST to your Gateway's webhook endpoint.

Troubleshooting

Cleanup

openclaw webhooks gmail stop

---

Standing Orders

Grant agents permanent operating authority for defined programs. Define in AGENTS.md.

Each program requires:

• Scope: What the agent can do
• Triggers: When it executes
• Approval gates: What needs human approval
• Escalation: When to stop and ask for help

Template

## Program: [Name]
**Authority:** [What agent can do]
**Trigger:** [When it executes]
**Approval gate:** [What needs human approval]
**Escalation:** [When to stop and ask for help]

Execution Discipline

Every task follows: Execute -> Verify -> Report.

---

---

Background Tasks

Background tasks track detached agent runs (cron, webhooks, sub-agents, etc.).

Note: ClawFlow (openclaw flows) is deprecated. Use openclaw tasks instead.

CLI

openclaw tasks list                 # List tracked detached runs
openclaw tasks show <lookup>        # Show specific task details
openclaw tasks cancel <lookup>      # Cancel a running task
openclaw tasks audit                # Identify problematic task runs

Migration from ClawFlow

---

Hooks

Event-driven system for automating actions within the Gateway.

Discovery Layers (Priority Order)

1. Bundled hooks 2. Plugin hooks 3. Managed hooks (~/.openclaw/hooks/) 4. Workspace hooks (<workspace>/hooks/, disabled by default)

Workspace hooks can introduce new hook names but cannot override hooks from higher-precedence sources.

Bundled Hooks

Event Categories

• Command: command:new, command:reset, command:stop
• Session: session:compact:before, session:compact:after, session:patch
• Agent: agent:bootstrap
• Gateway: gateway:startup
• Message: message:received, message:transcribed, message:preprocessed, message:sent

Hook Structure

my-hook/
├── HOOK.md          # Metadata (YAML frontmatter)
└── handler.ts       # Implementation

Hook Packs (npm Distribution)

Hook packs are npm packages exporting multiple hooks via openclaw.hooks in package.json:

openclaw plugins install <hook-pack-spec>

Plugin Hook API

Beyond event listeners, plugins can register sequential hooks:

28+ additional plugin hooks cover model I/O, lifecycle events, message flow, and subagent coordination.

CLI Commands

openclaw hooks list                 # Show all discovered hooks
openclaw hooks enable <name>        # Activate a hook
openclaw hooks disable <name>       # Deactivate a hook
openclaw hooks info <name>          # Detailed hook info
openclaw hooks check                # Eligibility summary

Bonjour / mDNS Discovery Reference

Source: https://docs.openclaw.ai/gateway/bonjour

Overview

OpenClaw uses Bonjour (mDNS/DNS-SD) to let companion apps (macOS, iOS, Android) discover the Gateway on the LAN automatically. The Gateway advertises a _openclaw-gw._tcp service.

Service Types

TXT Keys (Non-Secret Hints)

Security Notes

• TXT records are unauthenticated. Clients must not treat TXT as authoritative routing.
• Route using resolved SRV + A/AAAA records. Treat lanHost, tailnetDns, gatewayPort, gatewayTlsSha256 as hints only.
• TLS pinning must never allow advertised gatewayTlsSha256 to override a previously stored pin.
• iOS/Android nodes should treat discovery-based connects as TLS-only with user confirmation for first-time fingerprints.

Wide-Area Bonjour (Unicast DNS-SD over Tailscale)

For cross-network discovery (beyond LAN):

1. Run a DNS server on the gateway host (reachable over Tailnet). 2. Publish DNS-SD records under a dedicated zone (e.g., openclaw.internal.). 3. Configure Tailscale split DNS to resolve via that DNS server.

Gateway Config (Recommended)

{
  gateway: {
    bonjour: {
      domain: "openclaw.internal.",  // zone for wide-area DNS-SD
    },
  },
}

Debugging

On macOS

# Browse instances
dns-sd -B _openclaw-gw._tcp local.

# Resolve one instance
dns-sd -L "<instance>" _openclaw-gw._tcp local.

In Gateway Logs

Filter log file for bonjour::

• bonjour: advertise failed ...
• bonjour: ... name conflict resolved
• bonjour: watchdog detected non-announced service ...

On iOS Node

• Settings → Gateway → Advanced → Discovery Debug Logs
• Settings → Gateway → Advanced → Discovery Logs → reproduce → Copy

Common Failure Modes

Disabling / Configuration

{
  gateway: {
    bonjour: {
      enabled: false,  // disable entirely
    },
  },
}

See Also

• presence_discovery.md — Overview of presence + discovery
• remote_access.md — SSH, Tailscale remote access
• gateway_internals.md — Network model

Browser Tool — Detailed Reference

Full browser automation via CDP (Chrome DevTools Protocol). The browser tool is a bundled plugin shipping enabled by default. OpenClaw manages a separate browser profile for the agent with deterministic tab control.

What You Get

• A separate browser profile named openclaw (orange accent by default).
• Deterministic tab control (list/open/focus/close).
• Agent actions (click/type/drag/select), snapshots, screenshots, PDFs.
• Optional multi-profile support (openclaw, work, remote, …).

Quick Start

openclaw browser --browser-profile openclaw status
openclaw browser --browser-profile openclaw start
openclaw browser --browser-profile openclaw open https://example.com
openclaw browser --browser-profile openclaw snapshot

Plugin Loading Caveat

The browser is a bundled plugin. If you set plugins.allow, you must include "browser":

// BROKEN: browser tool missing
{ plugins: { allow: ["telegram"] } }

// FIXED: browser tool available
{ plugins: { allow: ["telegram", "browser"] } }

Note: tools.alsoAllow: ["browser"] does NOT load the plugin — it only adjusts tool policy after plugin loading. Disable browser entirely with plugins.entries.browser.enabled: false.

Profiles: openclaw vs user

• `openclaw`: Managed, isolated browser (no extension required).
• `user`: Built-in Chrome MCP attach profile for your real signed-in Chrome session (uses driver: "existing-session").

{ browser: { defaultProfile: "openclaw" } }

Profile Types

• openclaw-managed: Dedicated Chromium instance with own user data dir + CDP port.
• existing-session: Attach to a running Chromium browser via Chrome DevTools MCP (e.g., user, brave profiles).
• remote: Explicit CDP URL (browser running elsewhere).

Notes:

• openclaw profile is auto-created if missing.
• user profile uses Chrome MCP auto-connect, targeting the default local Google Chrome profile.
• Local CDP ports allocate from 18800–18899 by default.
• Deleting a profile moves its local data directory to Trash.
• Use userDataDir for Brave, Edge, Chromium, or non-default Chrome profile.

Existing-Session Profiles

Attach to your real browser session via Chrome DevTools MCP:

{
  browser: {
    profiles: {
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
    },
  },
}

Requirements:

• Target browser is Chromium-based, version 144+
• Remote debugging enabled in browser's inspect page
• Accept the attach consent prompt in browser

Live attach smoke test:

openclaw browser --browser-profile user start
openclaw browser --browser-profile user status
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot --format ai

Configuration

{
  browser: {
    enabled: true,                    // default: true
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true,  // default trusted-network mode
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    remoteCdpTimeoutMs: 1500,        // remote CDP HTTP timeout
    remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket timeout
    defaultProfile: "chrome",         // "openclaw" for managed browser
    color: "#FF4500",
    headless: false,
    noSandbox: false,
    attachOnly: false,                // never launch; attach only
    executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work:     { cdpPort: 18801, color: "#0066CC" },
      user: {
        driver: "existing-session",
        attachOnly: true,
        color: "#00AA00",
      },
      remote:   { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
  },
}

Port Convention

• Browser control service: gateway.port + 2 (default: 18791).
• Relay port: 18792.
• Per-profile CDP ports: 18800–18899.

If you override gateway.port, derived browser ports shift to the same "family".

Use Brave (or Another Chromium Browser)

// macOS
{ browser: { executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser" } }
// Windows
{ browser: { executablePath: "C:\\Program Files\\BraveSoftware\\Brave-Browser\\Application\\brave.exe" } }
// Linux
{ browser: { executablePath: "/usr/bin/brave-browser" } }

Or via CLI:

openclaw config set browser.executablePath "/usr/bin/google-chrome"

Browser Auto-Detection Order

1. Chrome → 2. Brave → 3. Edge → 4. Chromium → 5. Chrome Canary

• macOS: checks /Applications and ~/Applications.
• Linux: looks for google-chrome, brave, microsoft-edge, chromium, etc.
• Windows: checks common install locations.

Local vs Remote Control

• Local control (default): Gateway starts loopback control service, can launch a local browser.
• Remote control (node host): Run a node host on the browser machine; Gateway proxies browser actions.
• Remote CDP: Set browser.profiles.<name>.cdpUrl or browser.cdpUrl to attach to a remote Chromium browser. No local browser launched.

Auth for remote CDP:

• Query tokens: https://provider.example?token=<token>
• HTTP Basic auth: https://user:pass@provider.example

Node Browser Proxy (Zero-Config Default)

• Node host exposes its local browser control server via proxy.
• Profiles come from the node's own browser.profiles config.
• Disable:
• On the node: nodeHost.browserProxy.enabled=false
• On the gateway: gateway.nodes.browser.mode="off"

Browserless (Hosted Remote CDP)

{
  browser: {
    enabled: true,
    defaultProfile: "browserless",
    remoteCdpTimeoutMs: 2000,
    remoteCdpHandshakeTimeoutMs: 4000,
    profiles: {
      browserless: {
        cdpUrl: "https://production-sfo.browserless.io?token=<BROWSERLESS_API_KEY>",
        color: "#00AA00",
      },
    },
  },
}

Browserbase (Hosted Remote CDP)

Cloud headless browser with CAPTCHA solving capabilities.

{
  browser: {
    enabled: true,
    defaultProfile: "browserbase",
    profiles: {
      browserbase: {
        cdpUrl: "wss://connect.browserbase.com?apiKey=<BROWSERBASE_API_KEY>",
        color: "#6B4FBB",
      },
    },
  },
}

Chrome Extension Relay

Chrome extension:

• Gateway or node host runs locally (same machine).
• Local relay server listens at loopback cdpUrl (default: http://127.0.0.1:18792).
• You click the OpenClaw Browser Relay extension icon on a tab to attach.
• Agent controls that tab via the normal browser tool by selecting the right profile.

Isolation Guarantees

• Dedicated user data dir: Never touches your personal browser profile.
• Dedicated ports: Avoids 9222 to prevent collisions with dev workflows.
• Deterministic tab control: Target tabs by targetId, not "last tab".

Agent Tool API

The browser tool supports:

• browser snapshot — returns a stable UI tree (AI or ARIA mode).
• browser act — uses snapshot ref IDs to click/type/drag/select.
• browser screenshot — captures pixels (full page or element).

Parameters:

• profile — choose a named browser profile.
• target — sandbox | host | node to select where the browser lives.
• Sandboxed sessions default to sandbox, non-sandbox to host.
• target: "host" in sandbox requires agents.defaults.sandbox.browser.allowHostControl=true.
• If a browser-capable node is connected, auto-routes unless you pin target.

Control API (Optional)

HTTP endpoints (optional, for programmatic control):

Auth: Authorization: Bearer <gateway token> or x-openclaw-password: <gateway password>.

Profile selection: append ?profile=<name> to any endpoint.

Security & Privacy

• The openclaw browser profile may contain logged-in sessions; treat as sensitive.
• browser act kind=evaluate / openclaw browser evaluate and wait --fn execute arbitrary JavaScript. Disable with browser.evaluateEnabled=false.
• For logins and anti-bot notes (X/Twitter, etc.), see Browser login.
• Keep Gateway/node host private (loopback or tailnet-only).
• Remote CDP endpoints are powerful; tunnel and protect them.

SSRF Policy

{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,            // strict public-only
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"],
    },
  },
}

• dangerouslyAllowPrivateNetwork defaults to true (trusted-network model).
• Navigation is SSRF-guarded before navigation and re-checked on final URL.

Snapshots and Refs

Two snapshot styles:

AI snapshot (numeric refs): openclaw browser snapshot (default --format ai)

• Actions: openclaw browser click 12, openclaw browser type 23 "hello"
• Internally resolved via Playwright's aria-ref

Role snapshot (role refs like `e12`): openclaw browser snapshot --interactive

• Actions: openclaw browser click e12, openclaw browser highlight e12
• Internally resolved via getByRole(...) (plus nth() for duplicates)
• Add --labels to include a viewport screenshot with overlayed e12 labels

Refs are not stable across navigations — re-run snapshot after navigating.

Wait Power-Ups

openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

CLI Quick Reference

openclaw browser status                              # Browser status
openclaw browser start --browser-profile openclaw    # Start managed browser
openclaw browser profiles                             # List profiles
openclaw browser open <url>                           # Open URL
openclaw browser snapshot                             # Take AI snapshot
openclaw browser snapshot --interactive               # Take role snapshot (e12 refs)
openclaw browser snapshot --interactive --labels      # With viewport label overlay
openclaw browser screenshot                           # Take screenshot
openclaw browser screenshot --full-page               # Full page screenshot
openclaw browser evaluate "<js>"                      # Run JavaScript
openclaw browser click <ref>                          # Click element by ref
openclaw browser type <ref> "text"                    # Type into element
openclaw browser navigate <url>                       # Navigate to URL
openclaw browser cookies get                          # Get cookies
openclaw browser cookies set <json>                   # Set cookies
openclaw browser trace start                          # Start trace recording
openclaw browser trace stop                           # Stop trace recording

Troubleshooting

See Browser troubleshooting for Linux-specific issues.

Channel Routing Reference

Source: https://docs.openclaw.ai/channels/channel-routing

Key Terms

Default Account

• channels.<channel>.defaultAccount chooses which account is used when outbound path has no accountId.
• In multi-account setups: must set explicit default (defaultAccount or accounts.default).

Session Key Shapes

Examples:

agent:main:telegram:group:-1001234567890:topic:42
agent:main:discord:channel:123456:thread:987654

Main DM Route Pinning

• Controlled by session.dmScope (default: main).
• lastRoute: uses last DM route.
• When allowFrom has exactly one non-wildcard entry that can be normalized to a concrete sender ID, and the inbound DM sender doesn't match — the DM is pinned to that owner.

Routing Rules (Agent Selection)

Resolution order (first match wins):

1. Exact peer match — bindings with peer.kind + peer.id 2. Parent peer match — thread inheritance 3. Guild + roles match (Discord) — guildId + roles 4. Guild match (Discord) — guildId 5. Team match (Slack) — teamId 6. Account match — accountId on the channel 7. Channel match — any account on that channel (accountId: "*") 8. Default agent — agents.list[].default, else first list entry, fallback to main

Broadcast Groups (Multiple Agents)

Run multiple agents for the same conversation:

{
  broadcast: {
    strategy: "parallel",
    "120363403215116621@g.us": ["alfred", "baerbel"],
    "+15555550123": ["support", "logger"],
  },
}

Mattermost Channel

Source: https://docs.openclaw.ai/channels/mattermost

Setup

openclaw plugins install @openclaw/mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
    },
  },
}

Features

• Native slash commands via plugin
• Access control for DMs (pairing/allowlist)
• Channel/group support
• Reactions and interactive buttons via message tool
• Directory adapter for user resolution
• Multi-account support

BlueBubbles (iMessage) Channel

Source: https://docs.openclaw.ai/channels/bluebubbles

Overview

• Runs on macOS via BlueBubbles helper app (bluebubbles.app)
• Recommended: macOS Sequoia (15); macOS Tahoe (26) works with known limitations
• Communicates via REST API
• Incoming via webhooks; outgoing via REST calls

Quick Start

{
  channels: {
    bluebubbles: {
      enabled: true,
      serverUrl: "http://192.168.1.100:1234",
      password: "example-password",
      webhookPath: "/bluebubbles-webhook",
    },
  },
}

Point BlueBubbles webhooks to: https://your-gateway-host:3000/bluebubbles-webhook?password=<password>

Security

• Webhook authentication is always required.
• OpenClaw rejects webhook requests without matching channels.bluebubbles.password.
• Password checked before reading/parsing webhook bodies.

Features

• Typing + read receipts
• Reactions (surfaced as system events)
• Edit, unsend, reply threading
• Message effects
• Group management
• Block streaming support
• Media + limits (per WhatsApp-style pipeline)

See Also

• channels.md — All channel setup guides
• channel_troubleshooting.md — Per-channel troubleshooting
• multi_agent.md — Multi-agent routing configuration

OpenClaw Channel Troubleshooting Reference

Per-channel deep diagnostics and failure signatures. Use this when messages aren't flowing or channels behave unexpectedly.

Table of Contents

• Universal Command Ladder
• WhatsApp Deep Troubleshooting
• Telegram Deep Troubleshooting
• Discord Deep Troubleshooting
• Slack Deep Troubleshooting
• Pairing System
• Group Chat Troubleshooting

Universal Command Ladder

Always start here:

openclaw status                    # 1. Quick overview
openclaw gateway status            # 2. Daemon running? RPC ok?
openclaw logs --follow             # 3. Watch for errors
openclaw doctor                    # 4. Config/service diagnostics
openclaw channels status --probe   # 5. Per-channel probes

Expected healthy output:

• Runtime: running
• RPC probe: ok
• Channel probes show connected/ready

WhatsApp Deep Troubleshooting

Setup

# Step 1: Configure access policy
openclaw config set channels.whatsapp.dmPolicy '"pairing"'
openclaw config set channels.whatsapp.allowFrom '["+15551234567"]' --json

# Step 2: Link via QR
openclaw channels login --channel whatsapp
# For specific account:
openclaw channels login --channel whatsapp --account work

# Step 3: Start and approve
openclaw gateway
openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

Deployment Patterns

Failure Signatures

WhatsApp Config Keys

• Access: dmPolicy, allowFrom, groupPolicy, groupAllowFrom, groups
• Delivery: textChunkLimit, chunkMode, mediaMaxMb, sendReadReceipts, ackReaction
• Multi-account: accounts.<id>.enabled, accounts.<id>.authDir
• Operations: configWrites, debounceMs
• Credential path: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json

Runtime Model

• Gateway owns the WhatsApp socket and reconnect loop
• Only one session per Gateway (Baileys constraint)
• Status and broadcast chats (@status, @broadcast) are ignored
• Use Bun runtime with caution — Node.js recommended for WhatsApp

Telegram Deep Troubleshooting

Setup

# Step 1: Create bot with @BotFather
# /newbot → get token

# Step 2: Configure
openclaw config set channels.telegram.enabled true --json
openclaw config set channels.telegram.botToken '"123:abc"' --json
# Or use env: TELEGRAM_BOT_TOKEN=...

# Step 3: BotFather settings
# /setprivacy → Disable (for group messages without @mention)
# /setjoingroups → Allow (for group adds)

# Step 4: Start and approve
openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

Finding User IDs

Telegram user IDs are numeric. Find yours:

• Forward a message from yourself to @userinfobot
• Or use openclaw pairing list telegram to see pending IDs

Failure Signatures

Telegram Proxy

For VPS with unstable egress:

{
  channels: {
    telegram: {
      proxy: "socks5://user:pass@proxy-host:1080",
    },
  },
}

Telegram Network Env Overrides

OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1  # Force IPv4
OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first     # IPv4 preference

Validate DNS: dig +short api.telegram.org A && dig +short api.telegram.org AAAA

Telegram Features

• Streaming: channels.telegram.streaming → off | partial | block | progress
• Custom commands via channels.telegram.customCommands
• Native commands: commands.native: "auto" (default for Telegram)
• Forum topics isolate sessions with :topic:<threadId>

Discord Deep Troubleshooting

Setup

# Step 1: Create Discord app
# Discord Developer Portal → New Application → Bot → Message Content Intent

# Step 2: Enable required intents
# - Message Content Intent (REQUIRED)
# - Server Members Intent (recommended)

# Step 3: Generate invite URL with scopes: bot, applications.commands
# Permissions: View Channels, Send Messages, Read Message History, Embed Links, Attach Files

# Step 4: Enable Developer Mode
# User Settings → Advanced → Developer Mode → On
# Right-click server → Copy Server ID
# Right-click avatar → Copy User ID

# Step 5: Configure OpenClaw
openclaw config set channels.discord.token '"YOUR_BOT_TOKEN"' --json
openclaw config set channels.discord.enabled true --json
openclaw gateway restart

# Step 6: Approve pairing
openclaw pairing list discord
openclaw pairing approve discord <CODE>

Guild Workspace Setup

{
  channels: {
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        YOUR_SERVER_ID: {
          requireMention: true,          // false to respond to all messages
          users: ["YOUR_USER_ID"],       // Who can interact
        },
      },
    },
  },
}

Failure Signatures

Discord Runtime Model

• Reply routing is deterministic: Discord in → Discord out
• Guild channels isolated: agent:<agentId>:discord:channel:<channelId>
• DMs share main session by default (session.dmScope=main)
• Native slash commands: isolated sessions with CommandTargetSessionKey

Slack Deep Troubleshooting

Setup (Socket Mode)

# Step 1: Create Slack app
# Enable Socket Mode
# Create App Token (xapp-...) with connections:write
# Install app → copy Bot Token (xoxb-...)

# Step 2: Subscribe events
# app_mention, message.channels, message.groups, message.im, message.mpim
# reaction_added, reaction_removed, member_joined_channel, etc.

# Step 3: Configure

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",      // or "http"
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

Slack App Manifest

Copy-paste ready manifest for quick setup — see the full manifest in the Slack section of the OpenClaw docs.

Key scopes needed:

• chat:write, channels:history, channels:read
• groups:history, im:history, mpim:history
• users:read, app_mentions:read, assistant:write
• reactions:read, reactions:write, pins:read, pins:write
• emoji:read, commands, files:read, files:write

Failure Signatures

Pairing System

DM Pairing

When dmPolicy: "pairing" (default), unknown senders receive a one-time code:

• 8 characters, uppercase, no ambiguous chars (0O1I)
• Expires after 1 hour
• Max 3 pending requests per channel (additional requests ignored)
• Bot only sends pairing message once per ~hour per sender

openclaw pairing list --channel <channel>
openclaw pairing approve <channel> <CODE>

Node Device Pairing

For iOS/Android/macOS/headless nodes:

# Via Telegram (recommended for iOS)
# Send pairing command to bot

# Approve
openclaw pairing list --channel <channel> --type node
openclaw pairing approve --type node <CODE>

Pairing State

• DM pairings stored in channel allow-store
• Merged with configured allowFrom
• If no allowlist configured, linked self number is allowed by default
• Outbound fromMe DMs are never auto-paired

Group Chat Troubleshooting

Message Flow Decision Tree

groupPolicy? disabled → DROP
groupPolicy? allowlist → group in allowlist? NO → DROP
requireMention? YES → mentioned? NO → store for context only
OTHERWISE → REPLY

Common Issues

Mention Gating Config

{
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },
        "123@g.us": { requireMention: false },  // Specific group override
      },
    },
  },
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"],
        historyLimit: 50,
      },
    }],
  },
}

Per-Group Tool Restrictions

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: {
            "id:123456789": { alsoAllow: ["exec"] },  // Admin override
          },
        },
      },
    },
  },
}

OpenClaw Channel Reference

Table of Contents

• Supported Channels
• WhatsApp
• Telegram
• Discord
• Slack
• Signal
• iMessage / BlueBubbles
• Google Chat
• Microsoft Teams
• Matrix
• LINE
• Other Channels (Plugins)
• Channel CLI Commands
• Group Chat Configuration
• DM Access Policies
• Multi-Account Channels
• Troubleshooting

Supported Channels

Built-in (core)

Plugins (installed separately)

Feishu/Lark, Google Chat, Mattermost, Microsoft Teams, Synology Chat, LINE, Nextcloud Talk, Matrix, IRC, Nostr, Tlon, Twitch, Zalo, Zalo Personal.

Install plugins: openclaw plugins install <name>.

WhatsApp

# Pair via QR code
openclaw channels login --channel whatsapp

# Check status
openclaw channels status --probe

# Logout
openclaw channels logout --channel whatsapp

Config:

{
  channels: {
    whatsapp: {
      enabled: true,
      allowFrom: ["+15555550123"],       // Phone numbers
      groups: {
        "*": { requireMention: true },   // Mention gating for all groups
      },
    },
  },
}

Key notes:

• Only one WhatsApp session per Gateway (Baileys constraint)
• QR pairing required; re-pair if session expires
• WhatsApp stores significant state on disk
• Group messages require mention by default (requireMention)

Telegram

# Add bot with token
openclaw channels add --channel telegram --token <BOT_TOKEN>

# Or interactive
openclaw channels add --channel telegram

Config:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",           // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"],         // Telegram user IDs
      streaming: "partial",          // off | partial | block | progress
      inlineButtons: "dm",           // off | dm | group | all | allowlist
      reactions: "own",              // off | own | all
      webhook: {                     // Optional webhook mode (default: long-polling)
        enabled: false,
        url: "https://example.com/tg",
      },
    },
  },
}

Get token from @BotFather.

Features:

• Live stream preview modes: off | partial | block | progress — controls how partial responses are shown while generating
• HTML formatting with automatic Markdown conversion
• Native commands via setMyCommands — registers bot commands with BotFather automatically
• Inline buttons: off | dm | group | all | allowlist — attach interactive buttons to messages
• Forum topics with per-topic agent routing
• Audio/video/sticker support — send and receive media
• Reaction notifications: off | own | all — control when reactions trigger events
• Exec approvals with button-based workflows — approve or deny tool executions via inline buttons
• Webhook mode configuration — alternative to default long-polling

Limits:

• textChunkLimit: 4000 characters per message
• mediaMaxMb: 100 MB max upload
• historyLimit: 50 messages context

Discord

openclaw channels add --channel discord --token <BOT_TOKEN>

Config:

{
  channels: {
    discord: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
    },
  },
}

Requirements:

• Create bot at Discord Developer Portal
• Enable Message Content Intent
• Invite bot with proper permissions

Features:

• Interactive components — buttons, select menus, and modals
• Forum channels with auto-thread creation
• Voice channel support with TTS
• Thread binding — bind agent conversations to Discord threads
• Role-based routing — route messages to different agents based on Discord roles
• PluralKit support — recognize and handle PluralKit proxied messages
• Auto presence — automatically set bot status/activity

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",            // Required for Socket Mode (default)
      signingSecret: "...",
      slashCommands: false,            // Native slash commands (disabled by default)
      streaming: "partial",            // off | partial | block | progress
      channelPolicy: "open",          // open | allowlist | disabled
    },
  },
}

Uses Bolt SDK with Socket Mode as the default connection method. HTTP Events API is available as an alternative.

• App Token (xapp-...) is required for Socket Mode
• Native slash commands — disabled by default; enable to register commands with Slack
• Interactive replies — buttons and selects via Block Kit
• Ack reactions — adds a reaction emoji during processing to indicate the bot is working
• Text streaming modes: off | partial | block | progress
• Channel Policy: open (respond in any channel), allowlist (specified channels only), disabled

Signal

Uses signal-cli. Requires separate signal-cli setup and registration.

iMessage / BlueBubbles

Recommended: BlueBubbles (full feature support via REST API on macOS server).

Legacy iMessage via imsg CLI is deprecated.

Google Chat

Plugin: openclaw plugins install @openclaw/googlechat

Connects via the Google Chat API with HTTP webhooks.

Requirements:

• Google Cloud project with the Chat API enabled
• Service account with appropriate permissions
• Public HTTPS endpoint for receiving webhook events

Microsoft Teams

openclaw plugins install @openclaw/msteams

Requirements:

• Azure Bot resource with App ID, Client secret, and Tenant ID
• Messaging endpoint must be publicly accessible via HTTPS

Matrix

openclaw plugins install @openclaw/matrix

Features:

• E2EE support with cross-signing
• Thread support: off | inbound | always
• Multi-account — run multiple Matrix bot accounts
• Bot-to-bot communication
• autoJoin — automatically accept room invitations

LINE

openclaw plugins install @openclaw/line

Features:

• Flex cards — rich interactive message layouts
• Streaming with loading animations during generation
• Text chunking: 5000 characters per message
• Media limit: 10 MB

Other Channels (Plugins)

openclaw plugins list               # List available plugins
openclaw plugins install <name>     # Install a plugin
openclaw plugins info <name>        # Plugin details
openclaw plugins enable <name>      # Enable plugin
openclaw plugins disable <name>     # Disable plugin
openclaw plugins doctor             # Check plugin health

Channel CLI Commands

openclaw channels list              # Show configured channels + auth
openclaw channels status            # Channel health (add --probe for extra checks)
openclaw channels logs              # Recent channel logs from gateway
openclaw channels add               # Wizard-style setup
openclaw channels remove            # Disable (--delete to remove config)
openclaw channels login             # Interactive login (WhatsApp)
openclaw channels logout            # Log out of channel

Flags:

• --channel <name>: whatsapp|telegram|discord|slack|signal|imessage|googlechat|mattermost|msteams
• --account <id>: Account ID (default: "default")
• --name <label>: Display name

Group Chat Configuration

{
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"],
      },
    }],
  },
  channels: {
    whatsapp: {
      groups: {
        "*": { requireMention: true },              // All groups
        "specific-group-id": { requireMention: false }, // Override
      },
    },
  },
}

Per-Group Tool Restrictions

Restrict which tools are available on a per-group (and per-sender) basis:

{
  channels: {
    telegram: {
      groups: {
        "*": { tools: { deny: ["exec"] } },
        "-1001234567890": {
          tools: { deny: ["exec", "read", "write"] },
          toolsBySender: { "id:123456789": { alsoAllow: ["exec"] } },
        },
      },
    },
  },
}

• tools.deny — list of tools to block in a group
• toolsBySender — override tool restrictions for specific senders (by ID)
• alsoAllow — re-enable specific denied tools for a sender

DM Access Policies

Set per-channel dmPolicy:

Manage pairings:

openclaw pairing list --channel <channel>
openclaw pairing approve <id>

Multi-Account Channels

Channels like Discord and Telegram support multiple bot accounts:

openclaw channels add --channel telegram --account alerts --name "Alerts Bot" --token $TOKEN
openclaw channels add --channel discord --account work --name "Work Bot" --token $TOKEN
openclaw channels remove --channel discord --account work --delete

When adding a non-default account to a channel using single-account config, OpenClaw auto-migrates to multi-account structure.

Troubleshooting

Messages Not Flowing

openclaw channels status --probe
openclaw pairing list --channel <channel>
openclaw config get channels
openclaw logs --follow

Check for:

• mention required — group mention policy filtering
• pairing / pending approval — sender not approved
• missing_scope, Forbidden, 401/403 — channel auth/permissions issue

WhatsApp QR Issues

Re-pair: openclaw channels login --channel whatsapp --verbose

Channels Run Simultaneously

All configured channels run at once; OpenClaw routes per chat automatically.

ClawHub

Source: https://docs.openclaw.ai/tools/clawhub

What ClawHub Is

• A public registry for OpenClaw skills.
• A versioned store of skill bundles and metadata.
• A discovery surface for search, tags, and usage signals.

How It Works

1. A user publishes a skill bundle (files + metadata). 2. ClawHub stores the bundle, parses metadata, and assigns a version. 3. The registry indexes the skill for search and discovery. 4. Users browse, download, and install skills in OpenClaw.

Install the CLI

npm i -g clawhub
# or
pnpm add -g clawhub

How It Fits into OpenClaw

• Skills live in <workspace>/skills or ~/.openclaw/skills.
• clawhub --workdir <dir> or CLAWHUB_WORKDIR overrides the working directory.
• Default skills directory relative to workdir: skills.

Skill System Overview

• A SKILL.md file with the primary description and usage.
• Optional configs, scripts, or supporting files used by the skill.
• Metadata such as tags, summary, and install requirements.

Features

• Public browsing of skills and their SKILL.md content.
• Search powered by embeddings (vector search), not just keywords.
• Versioning with semver, changelogs, and tags (including latest).
• Downloads as a zip per version.
• Stars and comments for community feedback.
• Moderation hooks for approvals and audits.

Security and Moderation

• Any signed-in user can report a skill.
• Skills with more than 3 unique reports are auto-hidden by default.
• Moderators can view hidden skills, unhide, delete, or ban users.
• Abusing the report feature can result in account bans.

CLI Commands

Auth

clawhub login                       # Browser flow
clawhub login --token <token>       # API token
clawhub logout
clawhub whoami

Discovery

clawhub search "query"              # Search for skills
clawhub search "query" --limit <n>  # Limit results

Install & Update

clawhub install <slug>              # Install a skill
clawhub install <slug> --version <v> --force
clawhub update <slug>               # Update specific skill
clawhub update --all                # Update all skills
clawhub list                        # List installed (reads .clawhub/lock.json)

Publish & Sync

clawhub publish <path>              # Publish a skill
  --slug <slug>                     # Skill slug
  --name <name>                     # Display name
  --version <version>               # Semver version
  --changelog <text>                # Changelog text
  --tags <tags>                     # Comma-separated (default: latest)

clawhub sync                        # Sync all local skills
  --root <dir...>                   # Extra scan roots
  --all                             # Upload everything
  --dry-run                         # Preview only
  --bump <type>                     # patch|minor|major (default: patch)

clawhub delete <slug> --yes
clawhub undelete <slug> --yes

Global Options

Storage and Lockfile

• Installed skills tracked in .clawhub/lock.json.
• Each entry stores slug, version, installed path, and checksum.

Environment Variables

• CLAWHUB_WORKDIR — override working directory
• CLAWHUB_REGISTRY — registry API URL override
• CLAWHUB_TOKEN — API token for CI/automation

OpenClaw Diffs Tool & Firecrawl Integration Reference

Table of Contents

• Diffs Tool
• Firecrawl Integration

---

Diffs Tool

Optional plugin that renders before/after text or unified patches as a gateway-hosted diff view, a PNG image, or both.

Quick Start

# Install the plugin
openclaw plugins install @openclaw/diffs
openclaw config set plugins.entries.diffs.enabled true

Enable

{
  plugins: {
    entries: {
      diffs: { enabled: true },
    },
  },
}

Typical Agent Workflow

1. Agent generates a diff (before/after text or unified patch) 2. Calls the diffs tool with the diff content 3. Tool renders the diff as a hosted HTML viewer and/or PNG image 4. Returns URL + optional image block to the agent

Input Reference

Output

Returns:

• viewerUrl: URL to the hosted diff viewer
• imagePath: path to rendered PNG (if format includes image)
• imageBlock: image content block for the model

Plugin Defaults

{
  plugins: {
    entries: {
      diffs: {
        config: {
          format: "both",        // viewer + image
          maxLines: 5000,
          darkMode: true,
        },
      },
    },
  },
}

Security

• Viewer URLs are Gateway-scoped (accessible only via Gateway auth)
• Artifacts are cleaned up based on lifecycle policy
• No external network calls required

Browser Requirements (Image Mode)

• Image rendering requires a browser (Playwright/Chromium) when generating PNG
• Falls back to viewer-only if browser is unavailable

Troubleshooting

---

Firecrawl Integration

Firecrawl is an optional anti-bot fallback for the web_fetch tool. When regular fetching fails (e.g., Cloudflare protection), Firecrawl can bypass these protections.

Get an API Key

Sign up at https://firecrawl.dev and get an API key.

Configure

{
  tools: {
    web: {
      fetch: {
        firecrawl: {
          apiKey: "${FIRECRAWL_API_KEY}",
          // Or use SecretRef
        },
      },
    },
  },
}

Or set FIRECRAWL_API_KEY environment variable.

Stealth / Bot Circumvention

Firecrawl offers stealth mode for better anti-bot bypass:

{
  tools: {
    web: {
      fetch: {
        firecrawl: {
          apiKey: "...",
          stealth: true,    // Enable stealth mode
        },
      },
    },
  },
}

How web_fetch Uses Firecrawl

1. Agent calls web_fetch with a URL 2. OpenClaw tries the standard fetcher first 3. If the standard fetch fails (anti-bot block, empty content, etc.), it falls back to Firecrawl 4. Firecrawl fetches the page and returns cleaned content 5. Result is returned to the agent

The fallback is automatic — no agent-side changes needed.

OpenClaw Elevated Mode Reference

Overview

Elevated mode (/elevated directives) allows sandboxed agents to temporarily execute commands on the gateway host, with configurable approval controls.

Directive Forms

Short form: /elev on|off|ask|full

What It Controls

• Host execution: Forces exec onto the gateway host (only matters when agent is sandboxed)
• Approvals: full skips exec approvals; on/ask honor allowlist/ask rules
• No-op for unsandboxed agents: Only affects gating, logging, and status
• Tool policy still applies: If exec is denied by tool policy, elevated cannot be used
• Separate from `/exec`: /exec adjusts per-session defaults for authorized senders

Resolution Order

1. Inline directive on the message (applies only to that message) 2. Session override (set by sending a directive-only message) 3. Global default (agents.defaults.elevatedDefault in config)

Setting a Session Default

• Send a message that is only the directive, e.g. /elevated full
• Confirmation reply: "Elevated mode set to full..." / "Elevated mode disabled."
• If unavailable, returns actionable error without changing state
• Send /elevated with no argument to see current level

Group Chat Behavior

• Elevated directives only honored when the agent is mentioned
• Command-only messages that bypass mention requirements are treated as mentioned

Availability + Allowlists

Feature Gate

{
  tools: {
    elevated: {
      enabled: true,          // Global baseline
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["user-id-123"],
      },
    },
  },
}

Per-Agent Gate

{
  agents: {
    list: [{
      id: "restricted",
      tools: {
        elevated: {
          enabled: false,      // Can only further restrict (both must allow)
          allowFrom: { ... },  // Sender must match BOTH global + per-agent
        },
      },
    }],
  },
}

Allowlist Matching

• Unprefixed entries match sender-scoped identity only (SenderId, SenderE164, From)
• Mutable sender metadata requires explicit prefixes:
• name:<value> → SenderName
• username:<value> → SenderUsername
• tag:<value> → SenderTag
• id:<value>, from:<value>, e164:<value> → explicit identity

Discord Fallback

If tools.elevated.allowFrom.discord is omitted, channels.discord.allowFrom is used as fallback. Set tools.elevated.allowFrom.discord (even []) to override.

Logging + Status

• Elevated exec calls logged at info level
• Session status includes elevated mode (e.g. elevated=ask, elevated=full)

Exec Approvals Reference

Exec approvals control whether and how shell commands run on the gateway host or a node. This page covers the approval flow, allowlists, safe bins, and forwarding.

Where It Applies

Exec approvals apply when host=gateway or host=node (not sandbox).

Settings and Storage

• Stored in ~/.openclaw/exec-approvals.json.
• Config keys under tools.exec.*.

Policy Knobs

Security (exec.security)

Ask (exec.ask)

Ask Fallback (askFallback)

Controls what happens when no approval UI is available (e.g., headless gateway).

Allowlist (Per Agent)

Commands approved via the approval flow are stored per-agent in ~/.openclaw/exec-approvals.json.

Auto-Allow Skill CLIs

autoAllowSkills can auto-approve commands from installed skills' CLIs.

Safe Bins (stdin-only)

Safe bins are small, stdin-only stream filters that can run without explicit allowlist entries:

• Configured via tools.exec.safeBins (e.g., jq, cat, head).
• tools.exec.safeBinTrustedDirs — additional trusted directories. Built-in defaults: /bin, /usr/bin.
• tools.exec.safeBinProfiles — custom argv policy per safe bin:
• minPositional — minimum positional args
• maxPositional — maximum positional args
• allowedValueFlags — allowed flags
• deniedFlags — denied flags

Interpreters like python3, node, ruby, bash are not safe bins — they can execute arbitrary code.

Run openclaw security audit to check safeBins config. Run openclaw doctor --fix to apply fixes.

Safe Bins versus Allowlist

• Safe bins: Implicit trust for simple stdin→stdout filters. No storage needed.
• Allowlist: Explicit trust for specific executable paths. Stored per-agent.

Control UI Editing

The Control UI provides a visual editor for the exec approvals allowlist.

Approval Flow

1. Agent calls exec with host=gateway or host=node. 2. If the command is not allowlisted and ask != off:

• Returns status: "approval-pending".
• Approval prompt is sent to the companion app, node host, or chat channel.

3. User approves or denies. 4. Returns Exec finished or Exec denied.

tools.exec.approvalRunningNoticeMs (default 10000) — emits Exec running notice for long-running approvals.

Approval Forwarding to Chat Channels

Exec approval prompts can be forwarded to chat channels for remote approval.

macOS IPC Flow

Uses macOS IPC to forward approval prompts between the gateway and companion app.

System Events

Exec completions generate system events that can trigger heartbeat wakes.

Implications

• Keep the allowlist minimal.
• Use security=allowlist + ask=on-miss for a balanced security posture.
• Use security=deny for maximum restriction.
• Review ~/.openclaw/exec-approvals.json regularly.