Implementation:Openclaw Openclaw ResolveSandboxConfigForAgent

ResolveSandboxConfigForAgent

ResolveSandboxConfigForAgent documents the resolveSandboxConfigForAgent function in src/agents/sandbox/config.ts and the resolveSandboxToolPolicyForAgent function in src/agents/sandbox/tool-policy.ts. These functions resolve the complete sandbox configuration and tool policy for a specific agent, merging per-agent overrides with global defaults.

Principle:Openclaw_Openclaw_Tool_Policy_Configuration

Source Locations

File	Lines	Description
src/agents/sandbox/config.ts	L126-172	resolveSandboxConfigForAgent()
src/agents/sandbox/tool-policy.ts	L71-142	resolveSandboxToolPolicyForAgent()
src/agents/sandbox/types.ts	L51-60	SandboxConfig type
src/agents/sandbox/types.ts	L19-26	SandboxToolPolicyResolved type

resolveSandboxConfigForAgent

Signature

export function resolveSandboxConfigForAgent(
  cfg?: OpenClawConfig,
  agentId?: string,
): SandboxConfig

Parameters

Parameter	Type	Default	Description
cfg	OpenClawConfig	undefined	The full gateway configuration. When undefined, all defaults are used.
agentId	string	undefined	The agent to resolve config for. When undefined, only global/default settings apply.

Return Type

export type SandboxConfig = {
  mode: "off" | "non-main" | "all";
  scope: SandboxScope;              // "session" | "agent" | "shared"
  workspaceAccess: SandboxWorkspaceAccess;  // "none" | "ro" | "rw"
  workspaceRoot: string;
  docker: SandboxDockerConfig;
  browser: SandboxBrowserConfig;
  tools: SandboxToolPolicy;         // { allow?: string[], deny?: string[] }
  prune: SandboxPruneConfig;        // { idleHours, maxAgeDays }
};

Resolution Algorithm

1. Load global defaults from cfg.agents.defaults.sandbox.
2. Load agent overrides from the specific agent's config via resolveAgentConfig(cfg, agentId).
3. Resolve scope using resolveSandboxScope(): agent scope takes priority, then global, then legacy perSession boolean, defaulting to "agent".
4. Resolve tool policy via resolveSandboxToolPolicyForAgent().
5. Merge all settings with agent-specific values overriding global values:
   • mode: agent > global > "off"
   • workspaceAccess: agent > global > "none"
   • workspaceRoot: agent > global > DEFAULT_SANDBOX_WORKSPACE_ROOT
   • docker: merged via resolveSandboxDockerConfig()
   • browser: merged via resolveSandboxBrowserConfig()
   • prune: merged via resolveSandboxPruneConfig()
   • tools: from resolved tool policy

Scope-Dependent Behavior

When the resolved scope is "shared", per-agent Docker, browser, and prune overrides are ignored. This prevents conflicting container settings when all agents share one container.

resolveSandboxToolPolicyForAgent

Signature

export function resolveSandboxToolPolicyForAgent(
  cfg?: OpenClawConfig,
  agentId?: string,
): SandboxToolPolicyResolved

Parameters

Parameter	Type	Default	Description
cfg	OpenClawConfig	undefined	The full gateway configuration.
agentId	string	undefined	The agent to resolve tool policy for.

Return Type

export type SandboxToolPolicyResolved = {
  allow: string[];
  deny: string[];
  sources: {
    allow: SandboxToolPolicySource;
    deny: SandboxToolPolicySource;
  };
};

export type SandboxToolPolicySource = {
  source: "agent" | "global" | "default";
  key: string;
};

Resolution Algorithm

1. Look up agent-specific tool policy at agents.list[].tools.sandbox.tools.allow and .deny.
2. Fall back to global policy at tools.sandbox.tools.allow and .deny.
3. Fall back to defaults (DEFAULT_TOOL_ALLOW and DEFAULT_TOOL_DENY).
4. Expand tool groups via expandToolGroups() for both allow and deny lists.
5. Auto-include image in the allow list if not explicitly denied and not already present, to support multimodal workflows in sandboxed sessions.
6. Track sources for each of allow and deny independently, recording whether the value came from agent config, global config, or defaults.

The allow and deny lists are resolved independently -- agent allow can override global allow while deny still comes from global, or vice versa.

Supporting Resolution Functions

Function	File	Purpose
resolveSandboxScope(params)	src/agents/sandbox/config.ts	Resolves scope from explicit scope, legacy perSession boolean, or default "agent".
resolveSandboxDockerConfig(params)	src/agents/sandbox/config.ts	Merges global and agent Docker settings. Agent overrides ignored for shared scope. Env vars are merged (agent over global); binds are concatenated.
resolveSandboxBrowserConfig(params)	src/agents/sandbox/config.ts	Merges global and agent browser settings. Agent overrides ignored for shared scope.
resolveSandboxPruneConfig(params)	src/agents/sandbox/config.ts	Merges global and agent prune settings. Agent overrides ignored for shared scope.
isToolAllowed(policy, name)	src/agents/sandbox/tool-policy.ts	Evaluates whether a tool name is permitted by a given policy. Deny takes precedence over allow; empty allow list means all tools allowed.
expandToolGroups(patterns)	src/agents/tool-policy.ts	Expands tool group references into individual tool names.

Tool Pattern Matching

The isToolAllowed() function supports three pattern types:

Pattern	Example	Behavior
Wildcard all	"*"	Matches any tool name.
Exact	"exec"	Matches only the exact tool name (case-insensitive).
Glob	"sessions_*"	Converted to a regex; * matches any characters.

Deny is checked first. If a tool matches any deny pattern, it is blocked. Then allow is checked; if the allow list is empty, all non-denied tools are permitted.

Related Pages

Uses Heuristic

• Heuristic:Openclaw_Openclaw_Config_Cascade_Resolution