Skip to content

LeoYeAI/agent-master-skills / skills/bengii-gemini-fix

openclaw

Flagged

Comprehensive guide for installing, configuring, operating, and troubleshooting OpenClaw — a self-hosted, multi-channel AI agent gateway. Use when the user asks about OpenClaw setup, configuration, channel management (WhatsApp/Telegram/Discord/Slack/iMessage/etc.), model provider setup, Gateway operations, multi-agent routing, security hardening, troubleshooting, or any maintenance task related to their local OpenClaw installation. Also use when encountering errors from `openclaw` CLI commands or the Gateway daemon.

FileKindSize
README.mdmarkdown7.5 KB
README_CN.mdmarkdown7.3 KB
SKILL.mdskill md18.7 KB
_meta.jsonconfig286 B
references/acp_agents.mdmarkdown12.6 KB
references/agent_runtime.mdmarkdown5.6 KB
references/architecture.mdmarkdown3.8 KB
references/automation.mdmarkdown5.8 KB
references/bonjour.mdmarkdown3.3 KB
references/browser.mdmarkdown8.5 KB
references/channel_routing.mdmarkdown4.0 KB
references/channel_troubleshooting.mdmarkdown11.6 KB
references/channels.mdmarkdown6.2 KB
references/clawhub.mdmarkdown3.6 KB
references/config_reference.mdmarkdown11.2 KB
references/diffs_firecrawl.mdmarkdown3.3 KB
references/elevated.mdmarkdown2.8 KB
references/exec.mdmarkdown6.5 KB
references/exec_approvals.mdmarkdown3.1 KB
references/gateway_internals.mdmarkdown7.7 KB
references/gateway_ops.mdmarkdown9.6 KB
references/heartbeat.mdmarkdown4.9 KB
references/hooks.mdmarkdown14.6 KB
references/install.mdmarkdown4.1 KB
references/llm_task.mdmarkdown2.6 KB
references/lobster.mdmarkdown7.8 KB
references/media.mdmarkdown4.2 KB
references/memory.mdmarkdown11.9 KB
references/model_failover.mdmarkdown3.1 KB
references/multi_agent.mdmarkdown4.4 KB
references/nodes.mdmarkdown8.8 KB
references/openprose.mdmarkdown2.6 KB
references/pairing.mdmarkdown3.1 KB
references/pdf_tool.mdmarkdown3.5 KB
references/platforms.mdmarkdown2.7 KB
references/plugins.mdmarkdown6.9 KB
references/polls.mdmarkdown2.2 KB
references/presence_discovery.mdmarkdown2.2 KB
references/providers.mdmarkdown6.0 KB
references/queue.mdmarkdown2.1 KB
references/remote_access.mdmarkdown4.7 KB
references/sandboxing.mdmarkdown5.6 KB
references/secrets.mdmarkdown5.4 KB
references/security.mdmarkdown24.5 KB
references/sessions.mdmarkdown8.9 KB
references/skills.mdmarkdown4.4 KB
references/slash_commands.mdmarkdown5.1 KB
references/streaming.mdmarkdown1.8 KB
references/subagents.mdmarkdown12.3 KB
references/thinking.mdmarkdown2.8 KB
references/tools.mdmarkdown13.3 KB
references/tui.mdmarkdown4.0 KB
references/voice.mdmarkdown2.7 KB
references/web_tools.mdmarkdown2.7 KB
references/web_ui.mdmarkdown4.5 KB

references/sandboxing.md

View on GitHub
# OpenClaw Sandboxing Reference

## Table of Contents

- [Overview](#overview)
- [What Gets Sandboxed](#what-gets-sandboxed)
- [Modes](#modes)
- [Scope](#scope)
- [Workspace Access](#workspace-access)
- [Custom Bind Mounts](#custom-bind-mounts)
- [Docker Configuration](#docker-configuration)
- [Browser Sandboxing](#browser-sandboxing)
- [Multi-Agent Overrides](#multi-agent-overrides)
- [Tool Policy Integration](#tool-policy-integration)
- [Minimal Enable Example](#minimal-enable-example)
- [Groups Pattern](#groups-pattern)

## Overview

Sandboxing runs agent tool execution (commands, file ops) inside Docker containers, isolating them from the host.

## What Gets Sandboxed

**Sandboxed:**
- Tool execution: `exec`, `read`, `write`, `edit`, `apply_patch`, `process`, `bash`
- Optional browser in sandbox container

**NOT sandboxed (runs on host):**
- The Gateway process itself
- Tools explicitly allowed to run on host (`tools.elevated`)
- Elevated exec bypasses sandboxing

## Modes

Config: `agents.defaults.sandbox.mode`

| Mode | Behavior |
|---|---|
| `"off"` | No sandboxing |
| `"non-main"` | Sandbox only non-main sessions (groups/channels). Main DM session runs on host |
| `"all"` | Every session runs in a sandbox |

> **Note:** `"non-main"` is based on `session.mainKey` (default `"main"`), not agent ID. Group/channel sessions use their own keys, so they are always non-main and will be sandboxed.

## Scope

Config: `agents.defaults.sandbox.scope`

| Scope | Isolation Level |
|---|---|
| `"session"` (default) | One container per session (strongest) |
| `"agent"` | One container per agent |
| `"shared"` | One container shared by all sandboxed sessions |

## Workspace Access

Config: `agents.defaults.sandbox.workspaceAccess`

| Mode | Behavior |
|---|---|
| `"none"` (default) | Tools see sandbox workspace under `~/.openclaw/sandboxes` |
| `"ro"` | Mounts agent workspace read-only at `/agent` (disables write/edit/apply_patch) |
| `"rw"` | Mounts agent workspace read/write at `/workspace` |

## Custom Bind Mounts

Config: `agents.defaults.sandbox.docker.binds`

Format: `"hostPath:containerPath:mode"` (mode = `ro` or `rw`)

```json5
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: [
            "/home/user/source:/source:ro",
            "/var/data/myapp:/data:ro",
          ],
        },
      },
    },
    list: [{
      id: "build",
      sandbox: {
        docker: {
          binds: ["/mnt/cache:/cache:rw"],  // Per-agent override
        },
      },
    }],
  },
}
```

**Safety rules:**
- OpenClaw blocks dangerous bind sources: `docker.sock`, `/etc`, `/proc`, `/sys`, `/dev`
- Use `:ro` for sensitive mounts (secrets, SSH keys, credentials)
- Binds bypass sandbox filesystem — they expose host paths directly

## Docker Configuration

```json5
{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          network: "none",              // Default: no egress (safest)
          // network: "bridge",          // Allow internet access
          readOnlyRoot: true,           // Default
          user: "1000:1000",            // Container user
          setupCommand: "apt-get update && apt-get install -y python3",
          env: {                        // Container environment vars
            MY_VAR: "value",
          },
        },
      },
    },
  },
}
```

**Network:**
- `"none"` (default): no network access (package installs will fail)
- `"bridge"`: allow internet
- `"host"`: **blocked** by OpenClaw
- `"container:<id>"`: **blocked** by default (namespace join risk)

**setupCommand:**
- Runs once per container at creation
- `user` must be root (`"0:0"`) for package installs
- `readOnlyRoot` must be `false` for writes
- Container does NOT inherit `process.env` — use `docker.env` for API keys

## Browser Sandboxing

Config: `agents.defaults.sandbox.browser`

- Auto-starts when browser tool needs it
- Uses dedicated Docker network `openclaw-sandbox-browser`
- noVNC observer access is password-protected
- Optional `cdpSourceRange` for CIDR allowlist (e.g., `172.21.0.1/32`)
- `allowHostControl` lets sandboxed sessions target host browser
- Separate bind mounts via `agents.defaults.sandbox.browser.binds`

## Multi-Agent Overrides

Per-agent sandbox config overrides defaults:

```json5
{
  agents: {
    list: [{
      id: "support",
      sandbox: {
        mode: "all",                    // Override mode
        scope: "session",
        workspaceAccess: "none",
        docker: { binds: [] },
      },
      tools: {
        sandbox: {
          tools: {
            allow: ["group:messaging"],
            deny: ["group:runtime", "group:fs"],
          },
        },
      },
    }],
  },
}
```

## Tool Policy Integration

Sandbox, tool policy, and elevated mode work together:

1. **Tool policy** (`tools.allow`/`tools.deny`) — what tools are available
2. **Sandbox** — where tools execute (host vs container)
3. **Elevated mode** (`tools.elevated`) — host bypass for specific commands

Debug with: `openclaw sandbox explain`

## Minimal Enable Example

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
}
```

## Groups Pattern

Personal DMs on host + groups in sandbox:

```json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",     // Groups are non-main → sandboxed
        scope: "session",
        workspaceAccess: "none",
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: ["group:messaging", "group:sessions"],
        deny: ["group:runtime", "group:fs", "group:ui", "nodes", "cron", "gateway"],
      },
    },
  },
}
```
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall