Configuration — tool policy

The policy layers that decide which tools a run may call: tools.profile, tool groups, the sandbox tool gate, tools.codeMode, and the allow/deny surfaces evaluated on top of them.

Tool profiles

tools.profile sets a base allowlist before tools.allow/tools.deny:

Full selects tools; it does not grant Full Access execution permissions. The chat Execution permissions menu controls what available tools may do in that session. Global, agent, provider, allow/deny, owner, filesystem, sandbox, and execution restrictions still apply. A catalog entry does not mean a tool or plugin is configured, connected, or authorized in the current session.

The agent's Tools settings include run-dependent tools such as github_identity_status, github_publish, and transcripts, so Disable All also adds explicit denies for them. Their catalog rows do not bypass the GitHub workspace and identity checks or the meeting transcript caller checks.

coding and messaging also include the theme tool and implicitly allow bundle-mcp (configured MCP servers).

The tts tool is not part of any restricted profile. To let an agent on minimal, coding, or messaging call it, add tts to tools.alsoAllow. Automatic TTS is not a tool, so profiles do not affect it.

An unset profile also leaves core tools unfiltered, but does not itself opt into optional plugin tools. Explicit full contributes a wildcard to plugin tool selection, including optional tools from enabled plugins. Plugin configuration, availability, and independent policy restrictions still apply.

The minimal, coding, and messaging profiles include gateway maintenance actions: update.run, restart, and update.cleanup, without configuration reads. Each requires an explicit owner request or operator-scheduled admission. Updates and restarts use runtime-supervised paths. Cleanup keeps the Gateway serving and permanently retires eligible rollback copies; dryRun previews. External-chat updates and restarts require current owner authorization and commands.restart; cleanup does not restart and is independent of that flag. Control UI requests retain their operator authorization.

The full profile and an unset profile retain the tool's configuration-read actions. In a limited profile, explicitly add gateway to tools.alsoAllow to enable config.get and config.schema.lookup. If a provider-specific profile is also limited, its alsoAllow must grant gateway too. Existing global, agent, provider, conversation, sandbox, and runtime allow/deny restrictions still decide whether the tool is available. Subagent and non-owner restrictions still apply.

Tool groups

suggest_task lets an agent propose confirmed follow-up work without starting it. The working directory must be absolute, but does not need to be a Git checkout. Local debugging and non-code tasks are supported. The Control UI shows the title and summary as an actionable chip; a Gateway-backed TUI shows an equivalent interactive prompt. Start in a new session opens a normal session in that directory and sends the full task prompt. The new session is instructed to ask the user before creating or switching to a worktree if isolation becomes necessary. There is no up-front worktree or execution-destination choice. dismiss_task withdraws a still-pending suggestion by the ephemeral task_id returned from suggest_task.

The tools are offered only when the initiating operator surface can receive and action Gateway task-suggestion events. Channel sessions and local/embedded TUI sessions do not receive them; channel transports need a portable typed task action before they can safely expose this flow. Suggestions are process-local and disappear when the Gateway restarts. Both tools remain in the coding profile and group:sessions, so normal tools.allow and tools.deny policy configures them automatically when the surface supports them.

openclaw delegates OpenClaw setup and repair. It belongs to both group:automation and group:openclaw, so existing group allows and denies now include this helper. Group denies override an explicit openclaw allow. The helper is not added to minimal, coding, or messaging; use tools.alsoAllow to select it with a restricted profile. Catalog discovery does not bypass its owner, sandbox, direct-call, or execution permission checks.

pdf belongs to both group:media and group:openclaw. Group denies also cover PDF and override an explicit pdf allow entry. If an existing configuration should keep PDF access, remove or narrow the conflicting group deny. Group grants do not bypass PDF model and authentication requirements.

transcripts appears in the Media section of the catalog but is not a member of group:media or group:openclaw, preserving existing group grants and denies. Select it explicitly by name or through the full profile; restricted profiles can use tools.alsoAllow. The current caller and capture access checks still apply.

MCP and plugin tools inside sandbox tool policy

Configured MCP servers are exposed as plugin-owned tools under the bundle-mcp plugin id. Normal tool profiles can allow them, but tools.sandbox.tools is an additional gate for sandboxed sessions. If sandbox mode is "all" or "non-main", include one of these entries in the sandbox tool allowlist when MCP/plugin tools should be visible:

• bundle-mcp for OpenClaw-managed MCP servers from mcp.servers
• the plugin id for a specific native plugin
• group:plugins for all loaded plugin-owned tools
• exact MCP server tool names or server globs such as outlook__send_mail or outlook__* when you only want one server

Server globs use the provider-safe MCP server prefix, not necessarily the raw mcp.servers key. Non-[A-Za-z0-9_-] characters become -, names that do not start with a letter get an mcp- prefix, and long or duplicate prefixes may be truncated or suffixed; for example, mcp.servers["Outlook Graph"] uses a glob like outlook-graph__*.

Per-run toolsAllow caps also accept globs such as outlook* or out*graph* for configured MCP servers. These globs can trigger catalog discovery across all enabled static MCP servers, just like outlook__*; they do not limit which servers connect. Discovery is conservative and can run even when no tool ultimately matches. Final tool allow/deny and sandbox policies still apply, disabled servers remain excluded unless explicitly enabled by a session override, and requester-scoped servers still require their verified requester context.

{  agents: { defaults: { sandbox: { mode: "all" } } },  mcp: {    servers: {      outlook: { command: "node", args: ["./outlook-mcp.js"] },    },  },  tools: {    sandbox: {      tools: {        alsoAllow: ["web_search", "web_fetch", "memory_search", "memory_get", "bundle-mcp"],      },    },  },}

Without that sandbox-layer entry, the MCP server can still load successfully while its tools are filtered before the provider request. Use openclaw doctor to catch this shape for OpenClaw-managed servers in mcp.servers. MCP servers loaded from bundled plugin manifests or Claude .mcp.json use the same sandbox gate, but this diagnostic does not enumerate those sources yet; use the same allowlist entries if their tools disappear in sandboxed turns.

tools.codeMode

tools.codeMode gates the generic OpenClaw code-mode surface. When engaged for a run with tools, normal OpenClaw tools move behind the guest catalog bridge, and MCP tools are available through the generated MCP namespace. The model normally sees exec and wait; tools such as computer whose structured results cannot cross the JSON-only bridge stay direct.

enabled defaults to false, including when the object sets other Code Mode options. To engage code mode only for models whose catalog entry flags compat.codeMode: "preferred", enable "auto" explicitly. See Code Mode - automatic per-model activation.

executor defaults to "node", which uses node:vm for trusted host execution, not security isolation. Set "quickjs" for the bundled hardened guest executor. Agent-level settings override the global choice. See Code Mode executors for the trust boundary and continuation behavior.

{  tools: {    codeMode: {      enabled: "auto",      executor: "node",    },  },}

The shorthand is also accepted:

{  tools: { codeMode: "auto" },}

enabled: true forces code mode on for every tool-capable run, regardless of model.

MCP declarations are exposed through the read-only virtual API file surface in code mode. Guest code can call API.list("mcp") and API.read("mcp/<server>.d.ts") to inspect TypeScript-style signatures before calling MCP.<server>.<tool>(). See Code Mode for the runtime contract, limits, and debugging steps.

tools.allow / tools.deny

Global tool allow/deny policy (deny wins). Case-insensitive, supports * wildcards. Applied even when Docker sandbox is off.

{  tools: { deny: ["browser", "canvas"] },}

write and apply_patch are separate tool ids. allow: ["write"] also enables apply_patch for compatible models, but deny: ["write"] does not deny apply_patch. To block all file mutation, deny group:fs or list each mutating tool explicitly:

{  tools: { deny: ["write", "edit", "apply_patch"] },}

The image inspection tool is view_image. If an older config still names image in an allow, alsoAllow, or deny list, run openclaw doctor --fix to rewrite supported global, per-agent, provider, sandbox, sender, channel, and Gateway policy surfaces. Doctor preserves patterns such as image* that may still match other tools and adds view_image when the pattern no longer covers inspection. Patterns that already cover both names, such as * or *image*, remain unchanged.

tools.gatewayPolicy

Deployment owners can require a concrete tool and action allowlist for model-directed work. OpenClaw applies this limit after ordinary tool and plugin grants, including owner-started conversations. Without this setting, existing tool policies behave as before.

{  tools: {    gatewayPolicy: {      allow: ["read", "exec", "sessions_list", "sessions"],      actions: { sessions: ["patch"] },    },  },}

This example permits only those underlying tools, subject to the other tool policies. allow is required; an empty array permits no underlying tools. Use concrete tool identities, including individual plugin tool names. Wildcards, tool groups and plugin-wide grants are rejected. Existing tool aliases, such as cron for automations, resolve to the same identity.

Every selected tool with an action field also needs an explicit actions entry. Its published schema contains only those actions, and execution requires an explicit permitted action. An empty action list withholds the tool. Action filtering supports a top-level string action field; unsupported action schemas fail clearly during assembly.

Tool Search and Code Mode remain available as dispatchers over the permitted catalog. They do not grant access to omitted tools. The execution check runs after hooks and approval preparation, so a hook cannot rewrite an allowed request into a prohibited action. Tool assembly captures the deployment policy; retained executors and catalogs keep that policy.

Adding, changing or removing tools.gatewayPolicy requires a Gateway restart. Deployment owners such as OCE supply the policy when deploying the Gateway and activate changes through restart or replacement after affected old work ends. Newly assembled tools then use the new deployment policy. Ordinary tool-policy settings keep their existing reload behavior.

This policy limits model-directed tools. Direct human Gateway administration keeps its existing authorization. It does not configure native Codex tools or restrict arbitrary Harness-local programs.

Automation scope and command jobs

The tool/action allowlist alone cannot distinguish an ordinary Agent-turn schedule from a command job. Add automation restrictions when model turns should keep caller-scoped scheduling:

{  tools: {    gatewayPolicy: {      allow: ["automations"],      actions: {        automations: [          "status",          "list",          "get",          "add",          "update",          "remove",          "run",          "runs",          "next_check",          "wake",        ],      },      automations: { scope: "caller", allowCommandJobs: false },    },  },}

scope: "caller" withholds administrative automation grants from model turns, including conversations started by administrators or configured channel owners and restored continuations. Existing caller ownership and visibility checks still apply.

allowCommandJobs: false rejects model creation, conversion, editing, enablement and manual execution of command jobs and on-exit command watchers. The Gateway checks the stored job as well as the requested change, so a patch that omits the payload kind cannot bypass the restriction. Ordinary Agent-turn schedules remain available. Use cron.triggers.enabled: false separately to disable streams, script payloads, condition triggers and event sources; that setting also applies to humans.

These automation fields affect model-directed calls. Direct authorized human UI, CLI and RPC administration remains available. Omit the fields to retain existing conversational administrator management. Changes follow the Gateway restart contract above.

tools.byProvider

Further restrict tools for specific providers or models. Order: base profile → provider profile → allow/deny.

{  tools: {    profile: "coding",    byProvider: {      anthropic: { profile: "minimal" },      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },    },  },}

tools.toolsBySender

Restricts tools for the current turn's originating requester. This is defense-in-depth on top of channel access control; sender values must come from the channel adapter, not message text. It does not authenticate other content in the model prompt; see Requester-scoped controls and prompt context.

{  tools: {    toolsBySender: {      "channel:discord:1234567890123": { alsoAllow: ["group:fs"] },      "id:guest-user-id": { deny: ["group:runtime", "group:fs"] },      "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] },    },  },}

Keys use explicit prefixes: channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName>, or "*". Channel ids are standard OpenClaw ids; aliases such as teams normalize to msteams. Run openclaw doctor --fix to migrate retired unprefixed keys to id: entries. Matching order is channel+id, id, e164, username, name, then wildcard. Prefer id: or channel: keys when granting extra tools because username: and name: match mutable sender attributes.

Per-agent agents.entries.*.tools.toolsBySender overrides the global sender match when it matches, even with an empty {} policy.

tools.elevated

Controls elevated exec access outside the sandbox:

{  tools: {    elevated: {      enabled: true,      allowFrom: {        whatsapp: ["+15555550123"],        discord: ["1234567890123", "987654321098765432"],      },    },  },}

• Per-agent override (agents.entries.*.tools.elevated) can only further restrict.
• /elevated on|off|ask|full stores state per session; inline directives apply to single message.
• Elevated exec bypasses sandboxing and uses the configured escape path (gateway by default, or node when the exec target is node).