{
  "title": "Sandbox vs Tool Policy vs Elevated",
  "content": "OpenClaw has three related (but different) controls:\n\n1. **Sandbox** (`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`) decides **where tools run** (Docker vs host).\n2. **Tool policy** (`tools.*`, `tools.sandbox.tools.*`, `agents.list[].tools.*`) decides **which tools are available/allowed**.\n3. **Elevated** (`tools.elevated.*`, `agents.list[].tools.elevated.*`) is an **exec-only escape hatch** to run on the host when you’re sandboxed.\n\nUse the inspector to see what OpenClaw is *actually* doing:\n\n* effective sandbox mode/scope/workspace access\n* whether the session is currently sandboxed (main vs non-main)\n* effective sandbox tool allow/deny (and whether it came from agent/global/default)\n* elevated gates and fix-it key paths\n\n## Sandbox: where tools run\n\nSandboxing is controlled by `agents.defaults.sandbox.mode`:\n\n* `\"off\"`: everything runs on the host.\n* `\"non-main\"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).\n* `\"all\"`: everything is sandboxed.\n\nSee [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).\n\n### Bind mounts (security quick check)\n\n* `docker.binds` *pierces* the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).\n* Default is read-write if you omit the mode; prefer `:ro` for source/secrets.\n* `scope: \"shared\"` ignores per-agent binds (only global binds apply).\n* Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.\n* Workspace access (`workspaceAccess: \"ro\"`/`\"rw\"`) is independent of bind modes.\n\n## Tool policy: which tools exist/are callable\n\n* **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)\n* **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`\n* **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`\n* **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`\n* **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`\n\n* `deny` always wins.\n* If `allow` is non-empty, everything else is treated as blocked.\n* Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.\n* `/exec` only changes session defaults for authorized senders; it does not grant tool access.\n  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`).\n\n### Tool groups (shorthands)\n\nTool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:\n\n* `group:runtime`: `exec`, `bash`, `process`\n* `group:fs`: `read`, `write`, `edit`, `apply_patch`\n* `group:sessions`: `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `session_status`\n* `group:memory`: `memory_search`, `memory_get`\n* `group:ui`: `browser`, `canvas`\n* `group:automation`: `cron`, `gateway`\n* `group:messaging`: `message`\n* `group:nodes`: `nodes`\n* `group:openclaw`: all built-in OpenClaw tools (excludes provider plugins)\n\n## Elevated: exec-only “run on host”\n\nElevated does **not** grant extra tools; it only affects `exec`.\n\n* If you’re sandboxed, `/elevated on` (or `exec` with `elevated: true`) runs on the host (approvals may still apply).\n* Use `/elevated full` to skip exec approvals for the session.\n* If you’re already running direct, elevated is effectively a no-op (still gated).\n* Elevated is **not** skill-scoped and does **not** override tool allow/deny.\n* `/exec` is separate from elevated. It only adjusts per-session exec defaults for authorized senders.\n\n* Enablement: `tools.elevated.enabled` (and optionally `agents.list[].tools.elevated.enabled`)\n* Sender allowlists: `tools.elevated.allowFrom.<provider>` (and optionally `agents.list[].tools.elevated.allowFrom.<provider>`)\n\nSee [Elevated Mode](/tools/elevated).\n\n## Common “sandbox jail” fixes\n\n### “Tool X blocked by sandbox tool policy”\n\nFix-it keys (pick one):\n\n* Disable sandbox: `agents.defaults.sandbox.mode=off` (or per-agent `agents.list[].sandbox.mode=off`)\n* Allow the tool inside sandbox:\n  * remove it from `tools.sandbox.tools.deny` (or per-agent `agents.list[].tools.sandbox.tools.deny`)\n  * or add it to `tools.sandbox.tools.allow` (or per-agent allow)\n\n### “I thought this was main, why is it sandboxed?”\n\nIn `\"non-main\"` mode, group/channel keys are *not* main. Use the main session key (shown by `sandbox explain`) or switch mode to `\"off\"`.",
  "code_samples": [
    {
      "code": "It prints:\n\n* effective sandbox mode/scope/workspace access\n* whether the session is currently sandboxed (main vs non-main)\n* effective sandbox tool allow/deny (and whether it came from agent/global/default)\n* elevated gates and fix-it key paths\n\n## Sandbox: where tools run\n\nSandboxing is controlled by `agents.defaults.sandbox.mode`:\n\n* `\"off\"`: everything runs on the host.\n* `\"non-main\"`: only non-main sessions are sandboxed (common “surprise” for groups/channels).\n* `\"all\"`: everything is sandboxed.\n\nSee [Sandboxing](/gateway/sandboxing) for the full matrix (scope, workspace mounts, images).\n\n### Bind mounts (security quick check)\n\n* `docker.binds` *pierces* the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (`:ro` or `:rw`).\n* Default is read-write if you omit the mode; prefer `:ro` for source/secrets.\n* `scope: \"shared\"` ignores per-agent binds (only global binds apply).\n* Binding `/var/run/docker.sock` effectively hands host control to the sandbox; only do this intentionally.\n* Workspace access (`workspaceAccess: \"ro\"`/`\"rw\"`) is independent of bind modes.\n\n## Tool policy: which tools exist/are callable\n\nTwo layers matter:\n\n* **Tool profile**: `tools.profile` and `agents.list[].tools.profile` (base allowlist)\n* **Provider tool profile**: `tools.byProvider[provider].profile` and `agents.list[].tools.byProvider[provider].profile`\n* **Global/per-agent tool policy**: `tools.allow`/`tools.deny` and `agents.list[].tools.allow`/`agents.list[].tools.deny`\n* **Provider tool policy**: `tools.byProvider[provider].allow/deny` and `agents.list[].tools.byProvider[provider].allow/deny`\n* **Sandbox tool policy** (only applies when sandboxed): `tools.sandbox.tools.allow`/`tools.sandbox.tools.deny` and `agents.list[].tools.sandbox.tools.*`\n\nRules of thumb:\n\n* `deny` always wins.\n* If `allow` is non-empty, everything else is treated as blocked.\n* Tool policy is the hard stop: `/exec` cannot override a denied `exec` tool.\n* `/exec` only changes session defaults for authorized senders; it does not grant tool access.\n  Provider tool keys accept either `provider` (e.g. `google-antigravity`) or `provider/model` (e.g. `openai/gpt-5.2`).\n\n### Tool groups (shorthands)\n\nTool policies (global, agent, sandbox) support `group:*` entries that expand to multiple tools:",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "Quick debug",
      "id": "quick-debug"
    },
    {
      "level": "h2",
      "text": "Sandbox: where tools run",
      "id": "sandbox:-where-tools-run"
    },
    {
      "level": "h3",
      "text": "Bind mounts (security quick check)",
      "id": "bind-mounts-(security-quick-check)"
    },
    {
      "level": "h2",
      "text": "Tool policy: which tools exist/are callable",
      "id": "tool-policy:-which-tools-exist/are-callable"
    },
    {
      "level": "h3",
      "text": "Tool groups (shorthands)",
      "id": "tool-groups-(shorthands)"
    },
    {
      "level": "h2",
      "text": "Elevated: exec-only “run on host”",
      "id": "elevated:-exec-only-“run-on-host”"
    },
    {
      "level": "h2",
      "text": "Common “sandbox jail” fixes",
      "id": "common-“sandbox-jail”-fixes"
    },
    {
      "level": "h3",
      "text": "“Tool X blocked by sandbox tool policy”",
      "id": "“tool-x-blocked-by-sandbox-tool-policy”"
    },
    {
      "level": "h3",
      "text": "“I thought this was main, why is it sandboxed?”",
      "id": "“i-thought-this-was-main,-why-is-it-sandboxed?”"
    }
  ],
  "url": "llms-txt#sandbox-vs-tool-policy-vs-elevated",
  "links": []
}