Openclaw Ops

---
name: openclaw-ops
description: >-
  Referencia operacional do OpenClaw — arquitetura, gateway, agentes,
  skills, channels, sessions, memoria, tools, config, seguranca e OAuth.
  Assets por topico para consulta sob demanda. Use para operar qualquer setup OpenClaw.
license: Apache-2.0
compatibility: claude-code
allowed-tools: Read Glob Grep WebFetch WebSearch
metadata:
  author: vector-labs
  version: "1.0"
tags: [devops, infrastructure, ai-agents]
complexity: advanced
featured: true
links:
  - label: Diagrama Interativo de Arquitetura
    url: https://skills.vectorlabs.com.br/openclaw-ops/arquitetura.html
    icon: "🏗️"
---

# OpenClaw Operations

Conhecimento operacional generico do OpenClaw. Nada especifico de instancia — serve para operar qualquer setup. Assets organizados por topico, leia o relevante para a tarefa. Para orquestracao multi-agente com Antfarm, veja a skill `antfarm-ops`.

## Diagrama Interativo

[Explorar arquitetura visual OpenClaw](https://skills.vectorlabs.com.br/openclaw-ops/arquitetura.html) — Visao drill-down com todos os componentes expansiveis, fronteiras entre OpenClaw e LLM Provider, e deep dive no sistema de memoria.

## Arquitetura (resumo)

Gateway WebSocket (:18789) = control plane unico (Node.js 22+). Recebe mensagens de Channels (40+), roteia para Agentes isolados via ReAct loop (reason → act → observe), usando Tools (~25 built-in) e Skills (SKILL.md runbooks). Estado em Sessions (JSONL), Memory (SQLite + vector embeddings), Git (workspace). Config: `~/.openclaw/openclaw.json` (JSON5).

## Assets

| Tarefa / Duvida | Asset |
|------------------|-------|
| Camadas, componentes, data flow, diretorios | `assets/architecture.md` |
| Gateway: lifecycle, protocol, bind, auth, discovery | `assets/gateway.md` |
| Agentes: criacao, isolamento, routing, workspace files (soul-based) | `assets/agents.md` |
| Skills: SKILL.md format, precedencia, ClawHub, metadata, gating | `assets/skills-system.md` |
| Channels: setup, politicas DM/grupo, pairing, media | `assets/channels.md` |
| Sessions, compaction, memoria, embeddings, persistencia | `assets/sessions-memory.md` |
| Tools, permissoes, profiles, policy precedence, sandbox, exec | `assets/tools-permissions.md` |
| openclaw.json: estrutura, keys, secrets, env, $include, hot-reload | `assets/config.md` |
| Seguranca: modelo de confianca, audit, sandbox, incident response | `assets/security.md` |
| CLI: todos os comandos com subcomandos | `assets/cli.md` |
| OAuth: lifecycle, auto-refresh, re-autenticacao manual, bugs | `assets/oauth.md` |
| URLs da documentacao oficial para web_fetch | `assets/docs-urls.md` |

## Checklist operacional

```bash
openclaw gateway health
openclaw --version
openclaw channels status
openclaw skills list --eligible
openclaw doctor
```

# Agentes

Cada agente = contexto de execução 100% isolado: workspace, auth, sessions, tools.

## CLI

```bash
openclaw agents list              # Listar agentes
openclaw agents list --bindings   # Com routing bindings
openclaw agents add <id>          # Wizard criação (workspace, auth, sessions)
openclaw agents delete <id>       # Remover
openclaw agents set-identity <id> # Alterar identidade
```

## Estrutura de um agente

- **Workspace:** diretório de trabalho (git repo). Path: `~/.openclaw/workspace` (main) ou `~/.openclaw/workspace-<id>`
- **agentDir:** credentials em `~/.openclaw/agents/<id>/agent/` — NUNCA compartilhar entre agentes (causa collision)
- **Sessions:** histórico em `~/.openclaw/agents/<id>/sessions/` (JSONL)
- **Tools profile:** perfil de permissões + deny/allow lists

## Workspace files (Soul-Based System)

| Arquivo | Função | Precedência no prompt |
|---------|--------|-----------------------|
| AGENTS.md | Regras operacionais, baseline não-negociável | Alta (após PI Core) |
| SOUL.md | Personalidade, tom, idioma (não afeta tools) | Média |
| IDENTITY.md | Nome, criatura, emoji, avatar | Metadata |
| USER.md | Perfil do humano (nome, timezone, contexto) | Contexto |
| TOOLS.md | Notas sobre ferramentas locais (não é registry) | Contexto |
| HEARTBEAT.md | Tarefas periódicas (checklist a cada N min) | Cron |
| MEMORY.md | Memória curada de longo prazo | Contexto |
| BOOTSTRAP.md | Guia inicial (deletar após primeiro run) | Apenas 1x |

Templates oficiais: https://docs.openclaw.ai/reference/templates/

Composição do system prompt: `Base PI Core → AGENTS.md → SOUL.md → Skills relevantes → Memory → Tool defs`

## Routing de mensagens (precedência alta → baixa)

1. Peer match exato (DM/grupo/canal ID)
2. Parent peer (thread inheritance)
3. Guild + role (Discord)
4. Guild ID only
5. Team ID (Slack)
6. Account ID
7. Channel wildcard
8. **Default agent (fallback)**

Bindings com múltiplos campos usam AND. Primeiro match no mesmo nível ganha.

## Multi-agent config

```json5
{
  "agents": {
    "list": [
      { "id": "main", "default": true, "workspace": "~/.openclaw/workspace" },
      { "id": "work", "workspace": "~/.openclaw/workspace-work",
        "model": { "primary": "anthropic/claude-sonnet-4-5" },
        "tools": { "profile": "coding", "deny": ["gateway"] },
        "groupChat": { "mentionPatterns": ["@work", "work"] }
      }
    ]
  },
  "bindings": [
    { "agentId": "work", "match": { "channel": "slack", "teamId": "T123" } }
  ]
}
```

## Inter-agent communication

```json5
{
  "tools": {
    "agentToAgent": { "enabled": false, "allow": ["agent1", "agent2"] }
  }
}
```

Session tools: `sessions_list`, `sessions_send`, `sessions_history`, `sessions_spawn`

## Sandbox por agente

```json5
{
  "sandbox": { "mode": "all", "scope": "agent" },
  "tools": { "profile": "coding", "deny": ["gateway", "cron"] }
}
```

Modes: `off`, `all`, `non-main`. Scopes: `agent`, `session`, `shared`.

## Docs oficiais
- Multi-agent: https://docs.openclaw.ai/concepts/multi-agent
- Agent workspace: https://docs.openclaw.ai/concepts/agent-workspace
- Agent runtime: https://docs.openclaw.ai/concepts/agent
- System prompt: https://docs.openclaw.ai/concepts/system-prompt

# Arquitetura OpenClaw

## Camadas

```
┌─ Interfaces: CLI, Web UI (Control UI), macOS app, iOS/Android nodes ─┐
├─ Gateway (WebSocket :18789) ─ Control Plane único ───────────────────┤
│  ├─ Session Router (mensagem → agente correto)                       │
│  ├─ Channel Adapters (WhatsApp/Baileys, Telegram/grammY, Discord...) │
│  ├─ Auth & Device Pairing (Ed25519 challenge-response)               │
│  └─ Event Bus (agent, presence, health, tick a cada 15s)             │
├─ Agent Runtime (PiEmbeddedRunner / Pi Agent Core) ───────────────────┤
│  ├─ Context Assembly: Base PI Core → AGENTS.md → SOUL.md → Skills    │
│  ├─ ReAct Loop: reason → act (tool) → observe → repeat              │
│  ├─ Tool Dispatch (com sandbox opcional Docker)                      │
│  ├─ Compaction (auto-summarização quando contexto enche)             │
│  └─ Memory (SQLite + vector embeddings, hybrid search)               │
├─ Storage ────────────────────────────────────────────────────────────┤
│  ├─ Config: openclaw.json (JSON5, hot-reload)                        │
│  ├─ Sessions: JSONL append-only por agente                           │
│  ├─ Memory: SQLite + embeddings (semantic + BM25)                    │
│  ├─ Workspaces: Git repos por agente                                 │
│  └─ Credentials: 0600 permissions                                    │
└──────────────────────────────────────────────────────────────────────┘
```

## Diretórios (~/.openclaw/)

```
~/.openclaw/
├── openclaw.json              # Config principal (JSON5)
├── agents/<id>/agent/         # Auth por agente
│   ├── auth-profiles.json     # OAuth tokens
│   └── models.json            # Model overrides por agente
├── workspace/                 # Workspace do agente principal (git repo)
│   ├── AGENTS.md / SOUL.md / IDENTITY.md / USER.md / TOOLS.md
│   ├── MEMORY.md / HEARTBEAT.md / BOOTSTRAP.md
│   ├── memory/                # Notas diárias (YYYY-MM-DD.md)
│   └── skills/                # Skills do workspace (maior precedência)
├── workspaces/                # Workspaces de agentes adicionais
├── skills/                    # Skills gerenciadas (2a precedência)
├── memory/<agentId>.sqlite    # Vector embeddings + FTS
├── browser/                   # Perfil Chrome/Playwright
├── credentials/               # Secrets (permissão 0600)
├── cron/jobs.json             # Cron jobs
├── plugins/                   # Extensões npm
├── identity/device.json       # Ed25519 keypair
├── canvas/                    # Canvas/A2UI server data
├── logs/ media/ devices/ delivery-queue/ subagents/
└── exec-approvals.json        # Allowlists de execução
```

## Data flow de uma mensagem

1. **Ingestion** — Adapter do canal (Baileys/grammY/discord.js) recebe evento
2. **Access Control** — Verifica allowlist, DM pairing, grupo
3. **Session Resolution** — Mapeia para session key (`agent:<id>:dm:<channel>:<peer>`)
4. **Context Assembly** — Carrega sessão, monta system prompt, injeta skills relevantes, busca memória
5. **Model Invocation** — Streaming para o LLM provider
6. **Tool Dispatch** — Intercepta tool calls, executa (sandbox se necessário), resultado volta ao contexto
7. **Response Delivery** — Formata para o canal (markdown, chunking, mídia), transmite, persiste sessão

Latência típica: access control ~10ms, disk load ~50ms, prompt assembly ~100ms, first token 200-500ms.

## Componentes-chave

- **Pi Agent Core** (`@mariozechner/pi-agent-core`): runtime do agente, ReAct loop
- **Pi AI** (`@mariozechner/pi-ai`): integrações com LLM providers
- **PiEmbeddedRunner**: execução embedida no gateway
- **Canal únicos por host**: WhatsApp (Baileys) exige single-device, 1 gateway por host
- **Canvas/A2UI**: servidor separado (:18793), agents geram HTML com atributos `a2ui-*`, interação bidirecional

## Docs oficiais
- Arquitetura: https://docs.openclaw.ai/concepts/architecture
- Agent runtime: https://docs.openclaw.ai/concepts/agent
- Agent loop: https://docs.openclaw.ai/concepts/agent-loop

# Channels

40+ canais suportados. Cada um tem adapter próprio, auth específica, e políticas configuráveis.

## CLI

```bash
openclaw channels list               # Canais configurados
openclaw channels status             # Status de cada canal
openclaw channels status --probe     # Com health check ativo
openclaw channels login --channel <name>   # Setup/pair de canal
openclaw channels logout <channel>         # Desconectar
```

## Canais principais

| Canal | Adapter | Auth |
|-------|---------|------|
| WhatsApp | Baileys (WhatsApp Web) | QR code / pairing code |
| Telegram | grammY | Bot token |
| Discord | discord.js | Bot token |
| Slack | Slack SDK | App token + bot token |
| Signal | signal-cli | Phone number |
| iMessage | imsg CLI (macOS only) | Native |
| Matrix | matrix-js-sdk | Homeserver + token |
| Google Chat | Google API | Service account |
| MS Teams | Bot Framework | App registration |

Lista completa: https://docs.openclaw.ai/channels/index.md

## Políticas de DM

| Policy | Comportamento |
|--------|---------------|
| `pairing` (default) | Desconhecidos recebem código (expira 1h, max 3 pendentes) |
| `allowlist` | Bloqueia desconhecidos, aceita apenas listados |
| `open` | Aceita todos (requer `"*"` explícito em allowFrom) |
| `disabled` | Ignora DMs |

```bash
openclaw pairing list <channel>            # Requests pendentes
openclaw pairing approve <channel> <code>  # Aprovar contato
```

## Políticas de grupo

- `requireMention: true` — só responde se mencionado
- `groupPolicy`: `"open"`, `"allowlist"`, `"disabled"`
- `groupAllowFrom`: lista de IDs ou `["*"]`

## Config de canal (openclaw.json)

```json5
{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "open",
      "allowFrom": ["+5511999999999"],
      "groups": {
        "*": { "requireMention": true },
        "group-id-123": { "requireMention": false }
      },
      "mediaMaxMb": 50,
      "debounceMs": 0
    },
    "telegram": {
      "enabled": true,
      "botToken": "${TELEGRAM_BOT_TOKEN}",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123456"],
      "groups": { "*": { "requireMention": true } }
    }
  }
}
```

## Mention patterns

```json5
{
  "agents": {
    "list": [{
      "id": "main",
      "groupChat": {
        "mentionPatterns": ["@bot", "bot", "hey bot"]
      }
    }]
  }
}
```

## Broadcast groups

Enviar mesma mensagem para múltiplos canais/grupos simultaneamente.
Doc: https://docs.openclaw.ai/channels/broadcast-groups

## Enviar mensagens via CLI

```bash
openclaw message send --target <id> --message "texto"
openclaw directory resolve --channel <ch> --name <peer>  # Lookup de ID
```

## Re-pair WhatsApp

WhatsApp pode desconectar. Re-pair:
```bash
openclaw channels login --channel whatsapp
```

## Troubleshooting

- Canal desconectado: `openclaw channels status --probe` → re-login
- WhatsApp single-device: apenas 1 gateway por conta
- Health monitor: `channelHealthCheckMinutes: 5` (default)
- Auto-restart: `channelMaxRestartsPerHour: 10` (default)

## Docs oficiais
- Overview: https://docs.openclaw.ai/channels/index.md
- WhatsApp: https://docs.openclaw.ai/channels/whatsapp
- Telegram: https://docs.openclaw.ai/channels/telegram
- Discord: https://docs.openclaw.ai/channels/discord
- Slack: https://docs.openclaw.ai/channels/slack
- Pairing: https://docs.openclaw.ai/channels/pairing
- Groups: https://docs.openclaw.ai/channels/groups
- Routing: https://docs.openclaw.ai/channels/channel-routing
- Troubleshooting: https://docs.openclaw.ai/channels/troubleshooting

# CLI Reference

60+ comandos. `openclaw <command> --help` para detalhes de qualquer um.

## Core

```bash
openclaw gateway run|start|stop|restart|status|health|discover|install|uninstall|call|usage-cost
openclaw agent                     # Turno único de execução
openclaw agents add|delete|list|set-identity
openclaw acp client [--session <key>]   # Agent Control Protocol bridge
openclaw sessions [--agent|--all-agents|--active N] | cleanup
openclaw config get|set|unset|validate
openclaw models set|list|aliases|fallbacks|set-image|scan|status
```

## Chat & Mensagens

```bash
openclaw channels list|login|logout|status [--probe]
openclaw pairing list|approve <channel> <code>
openclaw directory resolve --channel <ch> --name <peer>
openclaw message send --target <id> --message "texto"
openclaw message read [--channel <ch>]
```

## Skills & Extensões

```bash
openclaw skills list [--verbose|--eligible]
openclaw skills info <name>
openclaw skills check
openclaw skills install <slug>
openclaw plugins install|list|enable|disable|doctor
openclaw hooks list|enable|disable|install|check
```

## Browser

```bash
openclaw browser start|stop|status
openclaw browser open|navigate <url>
openclaw browser screenshot [--full-page]
openclaw browser snapshot [--format aria]
openclaw browser click|type|fill|scroll|hover|drag|wait
openclaw browser cookies|storage
openclaw browser pdf
```

## Automação

```bash
openclaw cron add|list|run|status|enable|disable|edit|runs
openclaw system                    # Events, heartbeat, presence
```

## Administração

```bash
openclaw doctor [--generate-gateway-token]
openclaw security audit [--deep|--fix|--json]
openclaw health
openclaw status [--all]
openclaw logs                      # Tail via RPC
openclaw memory search|reindex
openclaw devices
openclaw approvals allowlist|get|set
openclaw backup create|verify <path>
openclaw update check|download|apply|channel
openclaw sandbox list|recreate [--all|--agent|--session]
openclaw reset
openclaw --version
```

## Interfaces

```bash
openclaw dashboard                 # Control UI (browser)
openclaw tui                       # Terminal UI
openclaw onboard                   # Wizard interativo
openclaw configure                 # Config wizard
```

## Nodes (dispositivos remotos)

```bash
openclaw node run|start|stop|restart|status
openclaw nodes                     # Listar nodes conectados
openclaw dns                       # Tailscale + CoreDNS
```

## Docs oficiais
- CLI index: https://docs.openclaw.ai/cli/index.md
- Cada comando: https://docs.openclaw.ai/cli/<command>

# Configuration (openclaw.json)

Formato JSON5 (suporta comentários). Localização: `~/.openclaw/openclaw.json`. Defaults seguros se ausente.

## CLI

```bash
openclaw config get <key>          # Ler (dot notation: agents.defaults.model.primary)
openclaw config set <key> <value>  # Definir
openclaw config unset <key>        # Remover
openclaw config validate           # Validar schema
openclaw onboard                   # Wizard interativo
openclaw configure                 # Config wizard
```

## Root-level keys

| Key | Função |
|-----|--------|
| `agents` | Defaults, lista de agentes, model, workspace, concurrency |
| `channels` | Configs por canal (WhatsApp, Telegram, Discord...) |
| `gateway` | Port, bind, auth, reload, push notifications |
| `session` | DM scope, thread bindings, reset, maintenance |
| `cron` | Jobs, retention, concurrency |
| `hooks` | Webhooks endpoints e routing |
| `tools` | Permissões, exec security, fs restrictions, elevated |
| `browser` | Headless, noSandbox, SSRF policy |
| `skills` | Entries, load config, extra dirs |
| `audio` / `talk` | Voz e TTS |
| `ui` | Customização de interface |
| `logging` | Levels, redaction, output |
| `identity` | Device identity config |
| `bindings` | Multi-agent routing rules |
| `env` | Environment vars e secrets |
| `$include` | Incluir configs de outros arquivos |

## Estrutura agents

```json5
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "openai-codex/gpt-5.4",
        "fallbacks": ["anthropic/claude-sonnet-4-5"]
      },
      "workspace": "~/.openclaw/workspace",
      "compaction": { "mode": "safeguard" },
      "maxConcurrent": 4,
      "subagents": { "maxConcurrent": 8 },
      "heartbeat": {
        "every": "30m",
        "target": "last",
        "directPolicy": "allow"
      },
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      },
      "imageMaxDimensionPx": 1200
    },
    "list": [
      {
        "id": "main", "default": true,
        "name": "Bot Name",
        "workspace": "~/.openclaw/workspace",
        "tools": { "profile": "coding", "deny": ["gateway"] },
        "groupChat": { "mentionPatterns": ["@bot"] }
      }
    ]
  }
}
```

## $include (split de config)

```json5
{
  "agents": { "$include": "./agents.json5" },
  "channels": { "$include": "./channels.json5" },
  "broadcast": {
    "$include": ["./clients/a.json5", "./clients/b.json5"]  // Array: deep-merge
  }
}
```

- Single file: replace no objeto
- Array de files: deep-merge (último ganha)
- Nesting até 10 níveis
- Paths relativos resolvem do arquivo que inclui

## Environment & Secrets

```json5
{
  "env": {
    "API_KEY": "value",                         // Direto
    "vars": { "OTHER_KEY": "value" },           // Namespace
    "shellEnv": { "enabled": true, "timeoutMs": 15000 }  // Herdar do shell
  }
}
```

### Secret refs (em qualquer campo)

```json5
{ "source": "env", "provider": "default", "id": "ENV_VAR" }
{ "source": "file", "id": "/path/to/secret" }
{ "source": "exec", "id": "command-to-run" }
```

## Hot-reload

`gateway.reload.mode`:
- `hybrid` (default) — hot-apply mudanças seguras, auto-restart para críticas
- `hot` — apenas mudanças seguras (ignora críticas)
- `restart` — restart para toda mudança
- `off` — manual only

Mudanças críticas (requerem restart): port, bind, auth mode.

## Cron config

```json5
{
  "cron": {
    "enabled": true,
    "maxConcurrentRuns": 2,
    "sessionRetention": "24h",
    "runLog": { "maxBytes": "2mb", "keepLines": 2000 }
  }
}
```

## Models config

```json5
{
  "agents": {
    "defaults": {
      "model": { "primary": "provider/model", "fallbacks": ["..."] },
      "models": {
        "provider/model": { "alias": "ShortName" }
      }
    }
  },
  "auth": {
    "profiles": {
      "provider:default": {
        "type": "oauth",
        "provider": "openai-codex"
      }
    }
  }
}
```

## Docs oficiais
- Config: https://docs.openclaw.ai/gateway/configuration
- Config reference: https://docs.openclaw.ai/gateway/configuration-reference
- Config examples: https://docs.openclaw.ai/gateway/configuration-examples
- Secrets: https://docs.openclaw.ai/gateway/secrets
- Environment: https://docs.openclaw.ai/help/environment

# Documentacao Oficial OpenClaw — URLs para web_fetch

Indice completo: https://docs.openclaw.ai/llms.txt
Para URLs do Antfarm, veja a skill `antfarm-ops`.

## Gateway & Infra
- Config: https://docs.openclaw.ai/gateway/configuration
- Config reference: https://docs.openclaw.ai/gateway/configuration-reference
- Config examples: https://docs.openclaw.ai/gateway/configuration-examples
- Security: https://docs.openclaw.ai/gateway/security/index.md
- Remote access: https://docs.openclaw.ai/gateway/remote
- Tailscale: https://docs.openclaw.ai/gateway/tailscale
- Troubleshooting: https://docs.openclaw.ai/gateway/troubleshooting
- Health: https://docs.openclaw.ai/gateway/health
- Sandboxing: https://docs.openclaw.ai/gateway/sandboxing
- Sandbox vs Tools vs Elevated: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
- Secrets: https://docs.openclaw.ai/gateway/secrets
- Logging: https://docs.openclaw.ai/gateway/logging
- Protocol: https://docs.openclaw.ai/gateway/protocol
- Doctor: https://docs.openclaw.ai/gateway/doctor
- Network model: https://docs.openclaw.ai/gateway/network-model
- Heartbeat: https://docs.openclaw.ai/gateway/heartbeat
- Multiple gateways: https://docs.openclaw.ai/gateway/multiple-gateways
- Local models: https://docs.openclaw.ai/gateway/local-models

## Agentes & Runtime
- Agent runtime: https://docs.openclaw.ai/concepts/agent
- Agent loop: https://docs.openclaw.ai/concepts/agent-loop
- Agent workspace: https://docs.openclaw.ai/concepts/agent-workspace
- Multi-agent: https://docs.openclaw.ai/concepts/multi-agent
- System prompt: https://docs.openclaw.ai/concepts/system-prompt
- Compaction: https://docs.openclaw.ai/concepts/compaction
- Context: https://docs.openclaw.ai/concepts/context
- Memory: https://docs.openclaw.ai/concepts/memory
- Sessions: https://docs.openclaw.ai/concepts/session
- Session pruning: https://docs.openclaw.ai/concepts/session-pruning
- Session deep dive: https://docs.openclaw.ai/reference/session-management-compaction
- Sub-agents: https://docs.openclaw.ai/tools/subagents
- Presence: https://docs.openclaw.ai/concepts/presence
- Model failover: https://docs.openclaw.ai/concepts/model-failover
- Streaming: https://docs.openclaw.ai/concepts/streaming

## Templates de workspace
- AGENTS.md: https://docs.openclaw.ai/reference/templates/AGENTS.md
- SOUL.md: https://docs.openclaw.ai/reference/templates/SOUL.md
- IDENTITY.md: https://docs.openclaw.ai/reference/templates/IDENTITY.md
- USER.md: https://docs.openclaw.ai/reference/templates/USER.md
- TOOLS.md: https://docs.openclaw.ai/reference/templates/TOOLS.md
- HEARTBEAT.md: https://docs.openclaw.ai/reference/templates/HEARTBEAT.md
- BOOTSTRAP.md: https://docs.openclaw.ai/reference/templates/BOOTSTRAP.md

## Skills & Tools
- Skills: https://docs.openclaw.ai/tools/skills
- Skills config: https://docs.openclaw.ai/tools/skills-config
- Creating skills: https://docs.openclaw.ai/tools/creating-skills
- ClawHub: https://docs.openclaw.ai/tools/clawhub
- Tools overview: https://docs.openclaw.ai/tools/index.md
- Exec: https://docs.openclaw.ai/tools/exec
- Exec approvals: https://docs.openclaw.ai/tools/exec-approvals
- Browser: https://docs.openclaw.ai/tools/browser
- Web tools: https://docs.openclaw.ai/tools/web
- Elevated: https://docs.openclaw.ai/tools/elevated
- Slash commands: https://docs.openclaw.ai/tools/slash-commands
- Plugins: https://docs.openclaw.ai/tools/plugin
- Multi-agent sandbox: https://docs.openclaw.ai/tools/multi-agent-sandbox-tools

## Channels
- Overview: https://docs.openclaw.ai/channels/index.md
- WhatsApp: https://docs.openclaw.ai/channels/whatsapp
- Telegram: https://docs.openclaw.ai/channels/telegram
- Discord: https://docs.openclaw.ai/channels/discord
- Slack: https://docs.openclaw.ai/channels/slack
- Signal: https://docs.openclaw.ai/channels/signal
- iMessage: https://docs.openclaw.ai/channels/imessage
- Matrix: https://docs.openclaw.ai/channels/matrix
- Google Chat: https://docs.openclaw.ai/channels/googlechat
- MS Teams: https://docs.openclaw.ai/channels/msteams
- Pairing: https://docs.openclaw.ai/channels/pairing
- Groups: https://docs.openclaw.ai/channels/groups
- Routing: https://docs.openclaw.ai/channels/channel-routing
- Broadcast: https://docs.openclaw.ai/channels/broadcast-groups
- Troubleshooting: https://docs.openclaw.ai/channels/troubleshooting

## Automação
- Cron: https://docs.openclaw.ai/automation/cron-jobs
- Cron vs Heartbeat: https://docs.openclaw.ai/automation/cron-vs-heartbeat
- Hooks: https://docs.openclaw.ai/automation/hooks
- Webhooks: https://docs.openclaw.ai/automation/webhook
- Polls: https://docs.openclaw.ai/automation/poll
- Gmail PubSub: https://docs.openclaw.ai/automation/gmail-pubsub

## Providers
- Index: https://docs.openclaw.ai/providers/index.md
- OpenAI: https://docs.openclaw.ai/providers/openai
- Anthropic: https://docs.openclaw.ai/providers/anthropic
- OpenRouter: https://docs.openclaw.ai/providers/openrouter
- Ollama: https://docs.openclaw.ai/providers/ollama
- Bedrock: https://docs.openclaw.ai/providers/bedrock
- Together: https://docs.openclaw.ai/providers/together
- Mistral: https://docs.openclaw.ai/providers/mistral
- Quickstart: https://docs.openclaw.ai/providers/models

## Deploy
- DigitalOcean: https://docs.openclaw.ai/platforms/digitalocean
- Docker: https://docs.openclaw.ai/install/docker
- Fly.io: https://docs.openclaw.ai/install/fly
- VPS: https://docs.openclaw.ai/vps
- Kubernetes: https://docs.openclaw.ai/install/kubernetes
- Updating: https://docs.openclaw.ai/install/updating

## Segurança & Referência
- Security: https://docs.openclaw.ai/gateway/security/index.md
- Threat model: https://docs.openclaw.ai/security/THREAT-MODEL-ATLAS
- API costs: https://docs.openclaw.ai/reference/api-usage-costs
- Token costs: https://docs.openclaw.ai/reference/token-use
- Prompt caching: https://docs.openclaw.ai/reference/prompt-caching
- FAQ: https://docs.openclaw.ai/help/faq
- Troubleshooting: https://docs.openclaw.ai/help/troubleshooting
- Environment vars: https://docs.openclaw.ai/help/environment

## CLI (por comando)
https://docs.openclaw.ai/cli/<command> — substitua <command> pelo nome do comando.

# Gateway

Processo central Node.js — WebSocket server, control plane único. Tudo depende dele.

## Lifecycle

```bash
# Serviço (systemd/launchd)
openclaw gateway install       # Registrar como serviço
openclaw gateway start|stop|restart
openclaw gateway uninstall

# Foreground (debug)
openclaw gateway run

# Background sem serviço
nohup openclaw gateway --force --port 18789 &>/tmp/gw-out.log & disown
```

Demora ~15-20s para responder ao health check após iniciar.

## Health & Status

```bash
openclaw gateway status        # Estado do serviço + health probe
openclaw gateway health        # Health check direto
openclaw health                # Resumo rápido
openclaw gateway usage-cost    # Tokens consumidos
openclaw logs                  # Tail logs em tempo real via RPC
```

Logs em disco: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`

## Configuração

```json5
{
  "gateway": {
    "port": 18789,                          // Porta padrão
    "bind": "loopback",                     // loopback | lan | tailnet | auto | custom
    "mode": "local",
    "auth": {
      "mode": "token",                      // token | password | trusted-proxy | none
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    },
    "reload": {
      "mode": "hybrid",                     // hybrid | hot | restart | off
      "debounceMs": 300
    },
    "channelHealthCheckMinutes": 5,
    "channelMaxRestartsPerHour": 10
  }
}
```

`hybrid` = hot-apply mudanças seguras, auto-restart para críticas (porta, bind, auth).

## Protocolo WebSocket

### Handshake
1. Gateway envia `connect.challenge` (nonce + timestamp)
2. Cliente envia `connect` (protocol versions, role, scope, device identity + assinatura Ed25519)
3. Gateway responde `hello-ok` (protocol version, policies, tick interval 15s)

### Frame types
- **Request:** `{type:"req", id, method, params}` — client → server
- **Response:** `{type:"res", id, ok, payload|error}` — server → client
- **Event:** `{type:"event", event, payload, seq?}` — push async

Métodos side-effecting requerem idempotency keys.

### Roles
- **Operator** (CLI, Web UI, apps): scopes `operator.read/write/admin/approvals/pairing`
- **Node** (iOS/Android, headless): declara capabilities (camera, screen, canvas, exec)

## Bind modes

| Mode | Acesso | Uso |
|------|--------|-----|
| `loopback` | 127.0.0.1 only | Default, seguro |
| `lan` | Rede local | Com firewall |
| `tailnet` | Via Tailscale | Recomendado para remoto |
| `auto` | Auto-detect | Conveniência |
| `custom` | Manual | Avançado |

## Auth modes

| Mode | Descrição |
|------|-----------|
| `token` | Bearer token (recomendado). Gerar: `openclaw doctor --generate-gateway-token` |
| `password` | HTTP Basic via `OPENCLAW_GATEWAY_PASSWORD` |
| `trusted-proxy` | Delega auth para reverse proxy |
| `none` | Sem auth (apenas dev local) |

## Discovery

```bash
openclaw gateway discover      # Bonjour (LAN) + Tailscale wide-area
```

## Acesso remoto

- **SSH tunnel (recomendado):** `ssh -f -N -L 28789:127.0.0.1:18789 user@host`
- **Tailscale Serve:** HTTPS dentro do tailnet, gateway fica loopback
- **Tailscale Funnel:** HTTPS público (requer password auth)

## RPC direto

```bash
openclaw gateway call <method> [params...]
```

## Docs oficiais
- Config: https://docs.openclaw.ai/gateway/configuration
- Config reference: https://docs.openclaw.ai/gateway/configuration-reference
- Protocol: https://docs.openclaw.ai/gateway/protocol
- Security: https://docs.openclaw.ai/gateway/security/index.md
- Remote: https://docs.openclaw.ai/gateway/remote
- Troubleshooting: https://docs.openclaw.ai/gateway/troubleshooting
- Health: https://docs.openclaw.ai/gateway/health

# OAuth (OpenAI Codex)

## Token Lifecycle

- Access token expira a cada ~10 dias
- Refresh automático: quando access expira, OpenClaw usa o refresh_token para renovar (sob file lock)
- Tokens armazenados em `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
- Formato: `{ access, refresh, expires, accountId }`

## Verificar Status

```bash
openclaw models status
```

Mostra: provider, auth store, profiles, e resultado do token refresh.

## Quando Auto-Refresh Falha

O erro mais comum é `refresh_token_reused`:
```
"Your refresh token has already been used to generate a new access token. Please try signing in again."
```

Isso acontece quando o refresh token foi usado (por outro processo ou tentativa anterior) e o novo par de tokens não foi salvo.

## Re-autenticação Manual

O `models auth login` precisa de TTY interativo e um tunnel para a porta do callback OAuth.

### Passo a passo

```bash
# 1. Criar tunnel para a porta do callback (geralmente 1455)
ssh -f -N -L 1455:127.0.0.1:1455 user@host

# 2. Rodar login interativo (precisa de terminal real, não funciona via scripts)
ssh -t user@host "openclaw models auth login --provider openai-codex"
```

O CLI mostra um link OAuth. Fluxo:
1. Abrir o link no browser local
2. Autorizar na OpenAI
3. O browser redireciona para `localhost:1455/auth/callback?code=...`
4. Se o tunnel estiver ativo, o CLI recebe o callback automaticamente
5. Se pedir "Paste the redirect URL", copiar a URL completa da barra do browser e colar no terminal

### Após sucesso
- Reiniciar o gateway para que pegue o novo token
- Verificar com `openclaw models status`

### Importante
- **Não usar `openclaw onboard`** para renovar auth — ele reconfigura tudo do zero
- O `models auth login` **não pode** ser rodado via scripts/automação (precisa de TTY)
- A porta do callback pode variar (1455 é comum, verificar na URL do link)

## Bug Conhecido: Token Não Sincronizado Entre Agentes

Issue openclaw/openclaw#12685: quando múltiplos agentes compartilham o mesmo OAuth profile, o token renovado pode não ser sincronizado para todos os agents' `auth-profiles.json`. Se um agente de workflow falhar com OAuth error mas o main funciona, pode ser necessário copiar o token manualmente.

## Docs oficiais
- OAuth: https://docs.openclaw.ai/concepts/oauth
- Providers: https://docs.openclaw.ai/providers/index.md

# Segurança

## Modelo de confiança

OpenClaw = personal assistant. **1 operador trusted por gateway.** NÃO é multi-tenant hostil. Para usuários adversários, rodar gateways separados.

## Auditoria

```bash
openclaw security audit            # Básica
openclaw security audit --deep     # Profunda
openclaw security audit --fix      # Auto-corrigir
openclaw security audit --json     # Saída JSON
```

### Prioridade de findings
1. `open` + tools habilitados → travar DMs/grupos primeiro
2. Exposição pública (LAN bind, Funnel, sem auth) → corrigir imediatamente
3. Browser control remoto → tratar como acesso de operador
4. Permissões de arquivos (state/config/credentials não group/world-readable)
5. Plugins → só código trusted
6. Modelo → preferir modernos, instruction-hardened

## Autenticação

| Mode | Recomendação |
|------|-------------|
| `token` | Recomendado. `openclaw doctor --generate-gateway-token` |
| `password` | OK. Via `OPENCLAW_GATEWAY_PASSWORD` |
| `trusted-proxy` | Para reverse proxy com identity |
| `none` | Apenas dev local |

### Device pairing
- Ed25519 challenge-response
- Local (loopback/tailnet own) = auto-approved
- Remoto = requer approval explícita
- Devices aprovados recebem tokens persistentes
- Rotação: `device.token.rotate`, revogação: `device.token.revoke`

## DM & Channel access

- **Pairing** (default): código 1h, max 3 pendentes
- **Allowlist**: bloqueia desconhecidos
- **Open**: requer `"*"` explícito
- Responder a mensagens do bot NÃO bypassa allowlists

## Sandbox

```json5
{
  "sandbox": {
    "mode": "non-main",   // off | all | non-main
    "scope": "agent"       // agent | session | shared
  }
}
```

Workspace access: `"none"` | `"ro"` (/agent) | `"rw"` (/workspace)

## Permissões de arquivos

- `~/.openclaw/openclaw.json` → modo 600
- `~/.openclaw/` → modo 700
- `openclaw doctor` avisa e corrige

## Prompt injection

**Não resolvido.** System prompt = soft guidance. Hard enforcement via:
- Tool policy + deny lists
- Exec approvals
- Sandbox (Docker)
- Channel allowlists
- **Modelos maiores/recentes = mais robustos**

Fontes de conteúdo não-confiável: search results, browser pages, emails, attachments. Blast radius típico: exfiltração ou tool calls não intencionais.

## Browser security

- Usar perfil dedicado (não daily-driver)
- SSRF default: `dangerouslyAllowPrivateNetwork: true`
- Modo estrito: `false` + `hostnameAllowlist`
- Remote browser = acesso de operador

## Plugins

- Rodam in-process com Gateway = tratar como código trusted
- npm lifecycle scripts executam código na instalação
- Preferir `plugins.allow` allowlist
- Auditar `tools.profile` quando plugins instalados

## Flags perigosas (auditadas por `security audit`)

- `gateway.controlUi.allowInsecureAuth`
- `gateway.controlUi.dangerouslyDisableDeviceAuth`
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback`
- `hooks.*.allowUnsafeExternalContent`
- `tools.exec.applyPatch.workspaceOnly: false`
- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork`
- `sandbox.docker.dangerouslyAllow*`

Manter unset/false em produção.

## Baseline seguro (config recomendada)

```json5
{
  "gateway": {
    "mode": "local", "bind": "loopback",
    "auth": { "mode": "token", "token": "long-random-token" }
  },
  "session": { "dmScope": "per-channel-peer" },
  "tools": {
    "profile": "messaging",
    "deny": ["group:automation", "group:runtime", "group:fs", "sessions_spawn", "sessions_send"],
    "fs": { "workspaceOnly": true },
    "exec": { "security": "deny", "ask": "always" },
    "elevated": { "enabled": false }
  },
  "channels": {
    "whatsapp": { "dmPolicy": "pairing", "groups": { "*": { "requireMention": true } } }
  }
}
```

## Incident response

1. **Conter:** stop gateway ou `bind: "loopback"`, desabilitar DMs/grupos
2. **Rotacionar:** gateway token, remote token, provider keys, channel tokens
3. **Auditar:** `/tmp/openclaw/openclaw-YYYY-MM-DD.log` + `sessions/*.jsonl`
4. **Verificar:** `openclaw security audit --deep`

## Logging & Transcripts

- Transcripts em disco: `~/.openclaw/agents/<id>/sessions/*.jsonl`
- Acesso ao disco = trust boundary
- Redaction: `logging.redactSensitive: "tools"` (default on)
- Usar `openclaw status --all` (redacted) para diagnóstico

## Docs oficiais
- Security: https://docs.openclaw.ai/gateway/security/index.md
- Threat model: https://docs.openclaw.ai/security/THREAT-MODEL-ATLAS
- Sandboxing: https://docs.openclaw.ai/gateway/sandboxing

# Sessions & Memory

## Sessions

### Session keys (encode security boundaries)
- `agent:<id>:main` — sessão principal (full access)
- `agent:<id>:dm:<channel>:<peer>` — DM (sandboxed por padrão)
- `agent:<id>:group:<channel>:<group>` — Grupo (sandboxed por padrão)

### Storage
JSONL append-only em `~/.openclaw/agents/<id>/sessions/<key>.jsonl`.
Cada linha = um turno (user msg, agent thought, tool call, tool result, response).

### CLI
```bash
openclaw sessions                  # Listar
openclaw sessions --agent <id>     # Por agente
openclaw sessions --all-agents     # Todos
openclaw sessions --active 60      # Ativas nos últimos N min
openclaw sessions cleanup          # Manutenção + pruning
```

### Config
```json5
{
  "session": {
    "dmScope": "per-channel-peer",     // main | per-peer | per-channel-peer | per-account-channel-peer
    "reset": {
      "mode": "daily",                // daily | idle | manual
      "atHour": 4,                    // Hora do reset (daily mode)
      "idleMinutes": 120              // Minutos idle antes de reset
    },
    "threadBindings": {
      "enabled": true,
      "idleHours": 24,
      "maxAgeHours": 0                // 0 = sem limite
    },
    "maintenance": {
      "mode": "enforce",
      "pruneAfter": "7d",
      "maxEntries": 500,
      "rotateBytes": "10mb"
    }
  }
}
```

### dmScope
- `main` — todos os DMs compartilham sessão principal
- `per-peer` — isolado por sender
- `per-channel-peer` — isolado por canal + sender (recomendado)
- `per-account-channel-peer` — isolado por account + canal + sender

## Compaction (auto-summarização)

Quando contexto se aproxima do limit do modelo:
1. LLM gera sumário dos segmentos completos de conversa
2. Turns originais substituídos pelo sumário compacto
3. Marker de compaction gravado no JSONL
4. Info crítica preservada, raciocínio verbose cortado
5. **Memory flush** (opcional): promove detalhes importantes para MEMORY.md

Permite conversas infinitas mantendo continuidade semântica.

Config: `agents.defaults.compaction.mode: "safeguard"` (default)

## Memory System

### Arquitetura
- **Database:** `~/.openclaw/memory/<agentId>.sqlite`
- **Search:** Hybrid — vector embeddings (semântico) + BM25 (keyword)
- **Embedding providers (cascata):** local model → OpenAI → Gemini → disabled
- **Auto-reindex:** file watcher com 1.5s debounce

### CLI
```bash
openclaw memory search "<query>"   # Buscar na memória
openclaw memory reindex            # Reindexar embeddings
```

### Tipos de memória
| Tipo | Arquivo | Escopo |
|------|---------|--------|
| Longo prazo curada | MEMORY.md | Apenas sessão principal |
| Notas diárias | memory/YYYY-MM-DD.md | Por sessão |
| Git history | .git/ | Versionamento workspace |
| Transcripts | sessions/*.jsonl | Completos, per-agent |

### Regras de memória
- MEMORY.md só é lido/escrito na sessão principal (não em grupo/shared)
- Notas diárias: carrega hoje + ontem no início de cada sessão
- Para persistir: DEVE escrever em arquivo (não existem "mental notes")
- Memory search via tool `memory_search` (hybrid: vector + FTS)

## Docs oficiais
- Sessions: https://docs.openclaw.ai/concepts/session
- Session deep dive: https://docs.openclaw.ai/reference/session-management-compaction
- Session pruning: https://docs.openclaw.ai/concepts/session-pruning
- Compaction: https://docs.openclaw.ai/concepts/compaction
- Memory: https://docs.openclaw.ai/concepts/memory
- Context: https://docs.openclaw.ai/concepts/context

# Skills System

Skills = runbooks em SKILL.md que ensinam o agente a orquestrar tools. Não são plugins executáveis.

## CLI

```bash
openclaw skills list              # Todas
openclaw skills list --verbose    # Com detalhes
openclaw skills list --eligible   # Apenas prontas
openclaw skills info <name>       # Detalhes
openclaw skills check             # Verificar requisitos
openclaw skills install <slug>    # Instalar do ClawHub
```

## Precedência de carregamento (alta → baixa)

1. **Workspace:** `<workspace>/skills/<skill>/SKILL.md`
2. **Managed:** `~/.openclaw/skills/<skill>/SKILL.md`
3. **Bundled:** incluídas no pacote OpenClaw
4. **Extra dirs:** via `skills.load.extraDirs` em openclaw.json

Skills do workspace sobrescrevem managed que sobrescrevem bundled.

## Formato SKILL.md

```yaml
---
name: skill-name
description: O que a skill faz
homepage: https://example.com                    # Opcional, surfaced em UI
user-invocable: true                             # true = expõe como /slash command
disable-model-invocation: false                  # true = exclui do prompt
command-dispatch: tool                           # Bypassa modelo, dispatch direto
command-tool: tool-name                          # Tool alvo do dispatch
command-arg-mode: raw                            # Modo de argumentos
metadata: {"openclaw":{...}}                     # JSON single-line obrigatório
---

# Nome da Skill

## O que faz
## Inputs necessários
## Workflow (passos numerados)
## Formato de saída
## Guardrails
## Tratamento de falhas
## Exemplos
```

**Constraints:** metadata DEVE ser JSON em uma única linha. Multi-line YAML não suportado.

## Metadata (gating)

```json
{
  "openclaw": {
    "always": true,                    // Bypassa todos os gates, sempre injetada
    "emoji": "🔧",
    "os": ["darwin", "linux"],         // Restrição de plataforma
    "requires": {
      "bins": ["curl", "jq"],          // TODOS devem existir no PATH
      "anyBins": ["ffmpeg", "avconv"], // Pelo menos UM
      "env": ["API_KEY"],             // Env var deve existir ou estar em config
      "config": ["browser.enabled"]    // Paths em openclaw.json devem ser truthy
    },
    "primaryEnv": "API_KEY",           // Mapeado por skills.entries.*.apiKey
    "skillKey": "custom-key",          // Key customizada em config
    "install": [{                      // Spec de instalação automática
      "id": "brew", "kind": "brew",   // Kinds: brew, node, go, uv, download
      "formula": "tool", "bins": ["tool"],
      "os": ["darwin"]
    }]
  }
}
```

## Config de skills (openclaw.json)

```json5
{
  "skills": {
    "entries": {
      "skill-name": {
        "enabled": true,               // false desabilita mesmo se bundled
        "apiKey": { "source": "env", "provider": "default", "id": "VAR" },
        "env": { "MY_VAR": "value" },  // Injeta se var não existe
        "config": { "custom": "val" }
      }
    },
    "allowBundled": ["skill1"],        // Allowlist para bundled only
    "load": {
      "watch": true,                   // Hot-reload quando SKILL.md muda
      "watchDebounceMs": 250,
      "extraDirs": ["/path/to/more"]
    }
  }
}
```

## Injection seletiva

O runtime NÃO injeta todas as skills em todo turno. Injeta apenas as relevantes para o turno atual (exceto `always: true`). Snapshot acontece no início da sessão.

## Token impact

```
total = 195 + Σ(97 + nome + descrição + location)
~24 tokens por skill (overhead fixo)
```

## ClawHub (registry público)

```bash
clawhub install <slug>         # Instala em ./skills/ (workspace)
clawhub update --all
clawhub list
clawhub uninstall <slug>
clawhub login                  # Para publicar
clawhub publish                # Publicar skill
```

13,729+ skills, ~5,400 curadas. Categorias: Coding (1222), Web (938), DevOps (409), Search (352), Browser (335).

## Segurança

- Tratar skills de terceiros como código não-confiável. Ler antes de habilitar.
- `env` e `apiKey` injetam secrets no processo host, não no sandbox.
- Skills não concedem permissões de tools — permissões devem ser habilitadas separadamente.

## Docs oficiais
- Skills: https://docs.openclaw.ai/tools/skills
- Skills config: https://docs.openclaw.ai/tools/skills-config
- Criando skills: https://docs.openclaw.ai/tools/creating-skills
- ClawHub: https://docs.openclaw.ai/tools/clawhub

# Tools & Permissões

## Tools built-in (~25)

| Categoria | Tools |
|-----------|-------|
| Shell | `bash`, `exec` |
| Filesystem | `read`, `write`, `edit`, `apply_patch` |
| Browser | `browser_*` (via Playwright/Chrome CDP) |
| Web | `web_search`, `web_fetch` |
| Media | `image`, `tts` |
| Control plane | `gateway`, `cron`, `message` |
| Sessions | `sessions_list`, `sessions_send`, `sessions_history`, `sessions_spawn` |
| Memory | `memory_search` |
| Outros | `nodes`, `canvas`, `elevated` |

## Profiles de permissão

| Profile | Pode | Não pode |
|---------|------|----------|
| `coding` | ler, escrever, executar | UI, gateway, cron |
| `analysis` | ler, explorar | escrever, editar |
| `verification` | ler, executar | escrever |
| `testing` | ler, executar, browser | escrever |
| `pr` | ler, executar (gh) | escrever |
| `scanning` | ler, executar, web search/fetch | escrever |
| `messaging` | set restrito para assistentes | quase tudo |

## Tool policy precedence (narrowing — só restringe, nunca expande)

```
Tool Profile → Provider Profile → Global Policy → Provider Policy → Agent Policy → Group Policy → Sandbox Policy
```

Cada camada pode apenas REMOVER acesso, nunca adicionar.

## Config por agente

```json5
{
  "agents": {
    "list": [{
      "id": "dev-agent",
      "tools": {
        "profile": "coding",
        "deny": ["gateway", "cron", "message", "sessions_send"],
        "alsoAllow": ["web_search", "browser"]
      }
    }]
  }
}
```

## Exec security

```json5
{
  "tools": {
    "exec": {
      "security": "ask",       // deny | ask | allow
      "ask": "dangerous"       // always | dangerous | never
    },
    "fs": {
      "workspaceOnly": true    // Restringe read/write/edit ao workspace
    },
    "elevated": {
      "enabled": false,        // Escape hatch para exec no host
      "allowFrom": []          // Manter tight
    }
  }
}
```

## Exec approvals

```bash
openclaw approvals allowlist       # Editar allowlist por agente
openclaw approvals get             # Snapshot do estado
openclaw approvals set             # Restaurar
```

Approvals vinculam "contexto exato do request + operandos de arquivo locais". São guardrails de intenção do operador, não boundary multi-tenant.

## Sandbox (Docker)

```json5
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",     // off | all | non-main
        "scope": "agent",       // agent | session | shared
        "docker": {
          "setupCommand": "apt-get install -y curl"  // Roda 1x na criação
        }
      }
    }
  }
}
```

### Workspace access no sandbox
- `"none"` (default) — workspace inacessível
- `"ro"` — mount read-only em /agent
- `"rw"` — mount read-write em /workspace

### CLI sandbox
```bash
openclaw sandbox list                         # Status containers
openclaw sandbox recreate [--all|--agent|--session]  # Reset
```

## Tools de alto risco (deny por default)

```json5
{ "deny": ["gateway", "cron", "sessions_spawn", "sessions_send", "group:automation", "group:runtime", "group:fs"] }
```

## Docs oficiais
- Tools overview: https://docs.openclaw.ai/tools/index.md
- Exec: https://docs.openclaw.ai/tools/exec
- Exec approvals: https://docs.openclaw.ai/tools/exec-approvals
- Elevated: https://docs.openclaw.ai/tools/elevated
- Browser: https://docs.openclaw.ai/tools/browser
- Sandboxing: https://docs.openclaw.ai/gateway/sandboxing
- Sandbox vs tools vs elevated: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
- Multi-agent sandbox: https://docs.openclaw.ai/tools/multi-agent-sandbox-tools