Principle:Openclaw Openclaw Tool Policy Configuration

Tool Policy Configuration

Tool Policy Configuration is the principle of configuring per-agent sandbox modes, workspace access levels, and tool allow/deny lists to enforce least-privilege execution per agent. This allows operators to restrict what each agent can do, independent of other agents running on the same gateway.

Motivation

In a multi-agent gateway, different agents serve different purposes with different trust levels. A personal assistant might need full filesystem access and code execution, while a family group bot should be restricted to read-only operations. A work agent might need sandboxed execution with network access, while a public-facing agent should have no filesystem access at all.

Tool policy configuration provides the mechanism to enforce these boundaries at the per-agent level, layered on top of global defaults.

Sandbox Modes

Each agent can be configured with one of three sandbox modes:

Mode	Description
off	No sandboxing. The agent runs directly on the host with full access. This is the default.
non-main	Only non-main sessions (e.g., sub-agent sessions) are sandboxed. The main session runs on the host.
all	All sessions for this agent are sandboxed in Docker containers.

Sandbox Scope

When sandboxing is enabled, the scope determines container isolation granularity:

Scope	Description
session	One container per session. Maximum isolation but higher resource usage.
agent	One container per agent. Sessions share a container but are isolated from other agents. This is the default when scope is not specified.
shared	All agents share one container. Per-agent Docker overrides are ignored in this mode.

Workspace Access

The workspaceAccess setting controls how the agent's workspace directory is mounted in the sandbox:

Access	Description
none	Workspace is not mounted. The agent cannot access its workspace files from inside the container.
ro	Workspace is mounted read-only. The agent can read files but cannot modify them.
rw	Workspace is mounted read-write. The agent has full access to its workspace.

Tool Allow/Deny Lists

Per-agent tool policies use allow and deny lists to control which tools the agent can invoke:

• allow -- When specified, only listed tools are permitted (whitelist). An empty allow list means no tools.
• deny -- Listed tools are blocked regardless of the allow list (blacklist takes precedence).
• Tool names support exact matches and wildcard patterns (e.g., "sessions_*").
• Tool groups can be referenced and are expanded automatically.

The image tool is automatically included in the allow list for sandboxed sessions (unless explicitly denied) to support multimodal workflows.

Resolution Order

Tool policies are resolved with a clear precedence:

1. Agent-specific policy (agents.list[].tools.sandbox.tools) takes highest precedence.
2. Global policy (tools.sandbox.tools) applies when no agent-specific policy exists.
3. Defaults are used when neither agent nor global policy is configured.

Each of allow and deny is resolved independently, with source tracking ("agent", "global", or "default") for debugging.

Docker Configuration

Per-agent Docker settings allow overriding container configuration:

• image -- Custom Docker image per agent.
• setupCommand -- One-time setup script after container creation (e.g., "apt-get update && apt-get install -y git curl").
• network -- Network mode ("none", "bridge", etc.).
• memory/cpus -- Resource limits.
• env -- Environment variables (merged with global).
• binds -- Volume mounts (appended to global).

Per-agent Docker overrides are ignored when the resolved scope is "shared".

Design Constraints

• tools.elevated is global and sender-based; it is not configurable per agent.
• For group targeting, use groupChat.mentionPatterns so @mentions map to the intended agent.
• Session tools visibility can be scoped to "spawned" (only sessions spawned from this session) or "all".

Implementation

Implementation:Openclaw_Openclaw_ResolveSandboxConfigForAgent