Sandbox vs tool policy vs elevated

Sandbox vs tool policy vs elevated 문서는 OpenClaw 공식 문서(gateway/sandbox-vs-tool-policy-vs-elevated)를 한국어로 정리한 가이드입니다. Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates

한국어 가이드 범위: gateway/sandbox-vs-tool-policy-vs-elevated 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Quick debug
Sandbox: where tools run
Bind mounts (security quick check)
Tool policy: which tools exist/are callable
Tool groups (shorthands)
Elevated: exec-only "run on host"
Common "sandbox jail" fixes
"Tool X blocked by sandbox tool policy"
"I thought this was main, why is it sandboxed?"
관련 문서

상세 내용

본문

OpenClaw has three related but different controls:

Quick debug

Use the inspector to see what OpenClaw is actually doing:

주요 항목:

effective sandbox mode/scope/workspace access
whether the session is currently sandboxed (main vs non-main)
effective sandbox tool allow/deny (and whether it came from agent/global/default)
elevated gates and fix-it key paths

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Sandbox: where tools run

Sandboxing is controlled by agents.defaults.sandbox.mode:

주요 항목:

"off": everything runs on the host.
"non-main": only non-main sessions are sandboxed (common "surprise" for groups/channels).
"all": everything is sandboxed.

Bind mounts (security quick check)

For a per-agent configuration with several host folders, access modes, and the external-source safety opt-in, see Multiple folders for one agent.

주요 항목:

docker.binds pierces the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (:ro or :rw).
Default is read-write if you omit the mode; prefer :ro for source/secrets.
scope: "shared" ignores per-agent binds (only global binds apply).
OpenClaw validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
Non-existent leaf paths are still checked safely. If /workspace/alias-out/new-file resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
Binding /var/run/docker.sock effectively hands host control to the sandbox; only do this intentionally.
Workspace access (workspaceAccess) is independent of bind modes.

Tool policy: which tools exist/are callable

주요 항목:

Tool profile: tools.profile and agents.entries.*.tools.profile (base allowlist)
Provider tool profile: tools.byProvider[provider].profile and agents.entries.*.tools.byProvider[provider].profile
Global/per-agent tool policy: tools.allow/tools.deny and agents.entries.*.tools.allow/agents.entries.*.tools.deny
Provider tool policy: tools.byProvider[provider].allow/deny and agents.entries.*.tools.byProvider[provider].allow/deny
Sandbox tool policy (only applies when sandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny and agents.entries.*.tools.sandbox.tools.*
deny always wins.
If allow is non-empty, everything else is treated as blocked.
Tool policy is the hard stop: /exec cannot override a denied exec tool.
Tool policy filters tool availability by name; it does not inspect side effects inside exec. If exec is allowed, denying write, edit, or apply_patch does not make shell commands read-only.
/exec only changes session defaults for authorized senders; it does not grant tool access.
Provider tool keys accept either provider (e.g. google-antigravity) or provider/model (e.g. openai/gpt-5.4).
Gateway logs include agents/tool-policy audit entries when a tool policy step removes tools or a sandbox tool policy blocks a call. Use openclaw logs to see the rule label, config key, and affected tool names.

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support group:* entries that expand to multiple tools:

Group	Tools
`group:runtime`	`exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `screen`, `terminal`, `canvas`, `show_widget`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	most built-in OpenClaw tools (excludes the `read`/`write`/`edit`/`apply_patch`/`exec`/`process` fs and runtime primitives, `canvas`, and provider plugins)
`group:plugins`	all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Elevated: exec-only "run on host"

Elevated does not grant extra tools; it only affects exec.

주요 항목:

If you are sandboxed, /elevated on (or exec with elevated: true) runs outside the sandbox (approvals may still apply).
Use /elevated full to skip exec approvals for the session.
If you are already running direct, elevated is effectively a no-op (still gated).
Elevated is not skill-scoped and does not override tool allow/deny.
Elevated does not grant arbitrary cross-host overrides from host=auto; it follows the normal exec target rules and only preserves node when the configured/session target is already node.
/exec is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
Enablement: tools.elevated.enabled (and optionally agents.entries.*.tools.elevated.enabled)
Sender allowlists: tools.elevated.allowFrom.<provider> (and optionally agents.entries.*.tools.elevated.allowFrom.<provider>)

Common "sandbox jail" fixes

이 섹션의 세부 항목은 공식 문서 Common "sandbox jail" fixes를 참고하세요.

"Tool X blocked by sandbox tool policy"

주요 항목:

Disable sandbox: agents.defaults.sandbox.mode=off (or per-agent agents.entries.*.sandbox.mode=off)
Allow the tool inside sandbox:
remove it from tools.sandbox.tools.deny (or per-agent agents.entries.*.tools.sandbox.tools.deny)
or add it to tools.sandbox.tools.allow (or per-agent allow)
Check openclaw logs for the agents/tool-policy entry. It records the sandbox mode and whether the allow or deny rule blocked the tool.

"I thought this was main, why is it sandboxed?"

In "non-main" mode, group/channel keys are not main. Use the main session key (shown by sandbox explain) or switch mode to "off".

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Sandbox vs tool policy vs elevated

핵심 요약

Why a tool is blocked: sandbox runtime, tool allow/deny policy, and elevated exec gates

한국어 가이드 범위: gateway/sandbox-vs-tool-policy-vs-elevated 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Quick debug
Sandbox: where tools run
Bind mounts (security quick check)
Tool policy: which tools exist/are callable
Tool groups (shorthands)
Elevated: exec-only "run on host"
Common "sandbox jail" fixes
"Tool X blocked by sandbox tool policy"
"I thought this was main, why is it sandboxed?"
관련 문서

상세 내용

본문

OpenClaw has three related but different controls:

Quick debug

Use the inspector to see what OpenClaw is actually doing:

주요 항목:

effective sandbox mode/scope/workspace access
whether the session is currently sandboxed (main vs non-main)
effective sandbox tool allow/deny (and whether it came from agent/global/default)
elevated gates and fix-it key paths

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

Sandbox: where tools run

Sandboxing is controlled by agents.defaults.sandbox.mode:

주요 항목:

"off": everything runs on the host.
"non-main": only non-main sessions are sandboxed (common "surprise" for groups/channels).
"all": everything is sandboxed.

Bind mounts (security quick check)

For a per-agent configuration with several host folders, access modes, and the external-source safety opt-in, see Multiple folders for one agent.

주요 항목:

docker.binds pierces the sandbox filesystem: whatever you mount is visible inside the container with the mode you set (:ro or :rw).
Default is read-write if you omit the mode; prefer :ro for source/secrets.
scope: "shared" ignores per-agent binds (only global binds apply).
OpenClaw validates bind sources twice: first on the normalized source path, then again after resolving through the deepest existing ancestor. Symlink-parent escapes do not bypass blocked-path or allowed-root checks.
Non-existent leaf paths are still checked safely. If /workspace/alias-out/new-file resolves through a symlinked parent to a blocked path or outside the configured allowed roots, the bind is rejected.
Binding /var/run/docker.sock effectively hands host control to the sandbox; only do this intentionally.
Workspace access (workspaceAccess) is independent of bind modes.

Tool policy: which tools exist/are callable

주요 항목:

Tool profile: tools.profile and agents.entries.*.tools.profile (base allowlist)
Provider tool profile: tools.byProvider[provider].profile and agents.entries.*.tools.byProvider[provider].profile
Global/per-agent tool policy: tools.allow/tools.deny and agents.entries.*.tools.allow/agents.entries.*.tools.deny
Provider tool policy: tools.byProvider[provider].allow/deny and agents.entries.*.tools.byProvider[provider].allow/deny
Sandbox tool policy (only applies when sandboxed): tools.sandbox.tools.allow/tools.sandbox.tools.deny and agents.entries.*.tools.sandbox.tools.*
deny always wins.
If allow is non-empty, everything else is treated as blocked.
Tool policy is the hard stop: /exec cannot override a denied exec tool.
Tool policy filters tool availability by name; it does not inspect side effects inside exec. If exec is allowed, denying write, edit, or apply_patch does not make shell commands read-only.
/exec only changes session defaults for authorized senders; it does not grant tool access.
Provider tool keys accept either provider (e.g. google-antigravity) or provider/model (e.g. openai/gpt-5.4).
Gateway logs include agents/tool-policy audit entries when a tool policy step removes tools or a sandbox tool policy blocks a call. Use openclaw logs to see the rule label, config key, and affected tool names.

Tool groups (shorthands)

Tool policies (global, agent, sandbox) support group:* entries that expand to multiple tools:

Group	Tools
`group:runtime`	`exec`, `process`, `code_execution` (`bash` is accepted as an alias for `exec`)
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions`, `sessions_list`, `sessions_history`, `sessions_search`, `conversations_list`, `conversations_send`, `conversations_turn`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status`, `spawn_task`, `dismiss_task`
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `screen`, `terminal`, `canvas`, `show_widget`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`, `computer`
`group:agents`	`agents_list`, `get_goal`, `create_goal`, `update_goal`, `update_plan`, `ask_user`, `skill_workshop`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`
`group:openclaw`	most built-in OpenClaw tools (excludes the `read`/`write`/`edit`/`apply_patch`/`exec`/`process` fs and runtime primitives, `canvas`, and provider plugins)
`group:plugins`	all loaded plugin-owned tools, including configured MCP servers exposed through `bundle-mcp`

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Elevated: exec-only "run on host"

Elevated does not grant extra tools; it only affects exec.

주요 항목:

If you are sandboxed, /elevated on (or exec with elevated: true) runs outside the sandbox (approvals may still apply).
Use /elevated full to skip exec approvals for the session.
If you are already running direct, elevated is effectively a no-op (still gated).
Elevated is not skill-scoped and does not override tool allow/deny.
Elevated does not grant arbitrary cross-host overrides from host=auto; it follows the normal exec target rules and only preserves node when the configured/session target is already node.
/exec is separate from elevated. It only adjusts per-session exec defaults for authorized senders.
Enablement: tools.elevated.enabled (and optionally agents.entries.*.tools.elevated.enabled)
Sender allowlists: tools.elevated.allowFrom.<provider> (and optionally agents.entries.*.tools.elevated.allowFrom.<provider>)

Common "sandbox jail" fixes

이 섹션의 세부 항목은 공식 문서 Common "sandbox jail" fixes를 참고하세요.

"Tool X blocked by sandbox tool policy"

주요 항목:

Disable sandbox: agents.defaults.sandbox.mode=off (or per-agent agents.entries.*.sandbox.mode=off)
Allow the tool inside sandbox:
remove it from tools.sandbox.tools.deny (or per-agent agents.entries.*.tools.sandbox.tools.deny)
or add it to tools.sandbox.tools.allow (or per-agent allow)
Check openclaw logs for the agents/tool-policy entry. It records the sandbox mode and whether the allow or deny rule blocked the tool.

"I thought this was main, why is it sandboxed?"

In "non-main" mode, group/channel keys are not main. Use the main session key (shown by sandbox explain) or switch mode to "off".

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/gateway/sandbox-vs-tool-policy-vs-elevated
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw sandbox explain
openclaw sandbox explain --session agent:main:main
openclaw sandbox explain --agent work
openclaw sandbox explain --json

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}

Sandbox vs tool policy vs elevated

핵심 요약

문서 구성

상세 내용

본문

Quick debug

Sandbox: where tools run

Bind mounts (security quick check)

Tool policy: which tools exist/are callable

Tool groups (shorthands)

Elevated: exec-only "run on host"

Common "sandbox jail" fixes

"Tool X blocked by sandbox tool policy"

"I thought this was main, why is it sandboxed?"

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Sandbox vs tool policy vs elevated

핵심 요약

문서 구성

상세 내용

본문

Quick debug

Sandbox: where tools run

Bind mounts (security quick check)

Tool policy: which tools exist/are callable

Tool groups (shorthands)

Elevated: exec-only "run on host"

Common "sandbox jail" fixes

"Tool X blocked by sandbox tool policy"

"I thought this was main, why is it sandboxed?"

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드