Use this file to discover all available pages before exploring further.

Configuration — tools and custom providers

text

tools.*

config keys and custom provider / base-URL setup. For agents, channels, and other top-level config keys, see Configuration reference.

Tools

Tool profiles

text

tools.profile

sets a base allowlist before

text

tools.allow

text

tools.deny

note

Local onboarding defaults new local configs to `tools.profile: "coding"` when unset (existing explicit profiles are preserved).

Profile	Includes
text `minimal`	text `session_status` only
text `coding`	text `group:fs` , text `group:runtime` , text `group:web` , text `group:sessions` , text `group:memory` , text `cron` , text `image` , text `image_generate` , text `video_generate`
text `messaging`	text `group:messaging` , text `sessions_list` , text `sessions_history` , text `sessions_send` , text `session_status`
text `full`	No restriction (same as unset)

Tool groups

Group	Tools
text `group:runtime`	text `exec` , text `process` , text `code_execution` ( text `bash` is accepted as an alias for text `exec` )
text `group:fs`	text `read` , text `write` , text `edit` , text `apply_patch`
text `group:sessions`	text `sessions_list` , text `sessions_history` , text `sessions_send` , text `sessions_spawn` , text `sessions_yield` , text `subagents` , text `session_status`
text `group:memory`	text `memory_search` , text `memory_get`
text `group:web`	text `web_search` , text `x_search` , text `web_fetch`
text `group:ui`	text `browser` , text `canvas`
text `group:automation`	text `cron` , text `gateway`
text `group:messaging`	text `message`
text `group:nodes`	text `nodes`
text `group:agents`	text `agents_list`
text `group:media`	text `image` , text `image_generate` , text `video_generate` , text `tts`
text `group:openclaw`	All built-in tools (excludes provider plugins)

text
`tools.allow`
/
text
`tools.deny`

Global tool allow/deny policy (deny wins). Case-insensitive, supports

text

*

wildcards. Applied even when Docker sandbox is off.


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

text
`tools.byProvider`

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


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

text
`tools.elevated`

Controls elevated exec access outside the sandbox:


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

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

text
`tools.exec`


json5
{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.5"],
      },
    },
  },
}

text
`tools.loopDetection`

Tool-loop safety checks are disabled by default. Set

text

enabled: true

to activate detection. Settings can be defined globally in

text

tools.loopDetection

and overridden per-agent at

text

agents.list[].tools.loopDetection


json5
{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

Max tool-call history retained for loop analysis. Repeating no-progress pattern threshold for warnings. Higher repeating threshold for blocking critical loops. Hard stop threshold for any no-progress run. Warn on repeated same-tool/same-args calls. Warn/block on known poll tools (`process.poll`, `command_status`, etc.). Warn/block on alternating no-progress pair patterns.

warning

If `warningThreshold >= criticalThreshold` or `criticalThreshold >= globalCircuitBreakerThreshold`, validation fails.

text
`tools.web`


json5
{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // optional; omit for auto-detect
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

text
`tools.media`

Configures inbound media understanding (image/audio/video):


json5
{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // opt-in: send finished async video directly to the channel
      },
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      image: {
        enabled: true,
        timeoutSeconds: 180,
        models: [{ provider: "ollama", model: "gemma4:26b", timeoutSeconds: 300 }],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

text
`tools.agentToAgent`


json5
{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

text
`tools.sessions`

Controls which sessions can be targeted by the session tools (

text

sessions_list

text

sessions_history

text

sessions_send

Default:

text

tree

(current session + sessions spawned by it, such as subagents).


json5
{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

text
`tools.sessions_spawn`

Controls inline attachment support for

text

sessions_spawn


json5
{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

text
`tools.experimental`

Experimental built-in tool flags. Default off unless a strict-agentic GPT-5 auto-enable rule applies.


json5
{
  tools: {
    experimental: {
      planTool: true, // enable experimental update_plan
    },
  },
}

text
planTool
: enables the structured
text
update_plan
tool for non-trivial multi-step work tracking.
Default:
text
false
unless
text
agents.defaults.embeddedPi.executionContract
(or a per-agent override) is set to
text
"strict-agentic"
for an OpenAI or OpenAI Codex GPT-5-family run. Set
text
true
to force the tool on outside that scope, or
text
false
to keep it off even for strict-agentic GPT-5 runs.
When enabled, the system prompt also adds usage guidance so the model only uses it for substantial work and keeps at most one step
text
in_progress
.

text
`agents.defaults.subagents`


json5
{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

text
model
: default model for spawned sub-agents. If omitted, sub-agents inherit the caller's model.
text
allowAgents
: default allowlist of target agent ids for
text
sessions_spawn
when the requester agent does not set its own
text
subagents.allowAgents
(
text
["*"]
= any; default: same agent only).
text
runTimeoutSeconds
: default timeout (seconds) for
text
sessions_spawn
when the tool call omits
text
runTimeoutSeconds
.
text
0
means no timeout.
Per-subagent tool policy:
text
tools.subagents.tools.allow
/
text
tools.subagents.tools.deny
.

Custom providers and base URLs

OpenClaw uses the built-in model catalog. Add custom providers via

text

models.providers

in config or

text

~/.openclaw/agents/<agentId>/agent/models.json


json5
{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            contextTokens: 96000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

Provider field details

Interactive custom-provider onboarding infers image input for common vision model IDs such as GPT-4o, Claude, Gemini, Qwen-VL, LLaVA, Pixtral, InternVL, Mllama, MiniCPM-V, and GLM-4V, and skips the extra question for known text-only families. Unknown model IDs still prompt for image support. Non-interactive onboarding uses the same inference; pass

text

--custom-image-input

to force image-capable metadata or

text

--custom-text-input

to force text-only metadata.

Provider examples

Configuration — agents
Configuration — channels
Configuration reference — other top-level keys
Tools and plugins

OpenClaw Docs

Configuration — tools and custom providers

Tools

Tool profiles

note

Tool groups

text
`tools.allow`
/
text
`tools.deny`

text
`tools.byProvider`

text
`tools.elevated`

text
`tools.exec`

text
`tools.loopDetection`

warning

text
`tools.web`

text
`tools.media`

text
`tools.agentToAgent`

text
`tools.sessions`

text
`tools.sessions_spawn`

text
`tools.experimental`

text
`agents.defaults.subagents`

Custom providers and base URLs

Provider field details

Provider examples

Related

OpenClaw Docs

Configuration — tools and custom providers

Tools

Tool profiles

note

Tool groups

textCopytools.allow / textCopytools.deny

textCopytools.byProvider

textCopytools.elevated

textCopytools.exec

textCopytools.loopDetection

warning

textCopytools.web

textCopytools.media

textCopytools.agentToAgent

textCopytools.sessions

textCopytools.sessions_spawn

textCopytools.experimental

textCopyagents.defaults.subagents

Custom providers and base URLs

Provider field details

Provider examples

Related

text
`tools.allow`
/
text
`tools.deny`

text
`tools.byProvider`

text
`tools.elevated`

text
`tools.exec`

text
`tools.loopDetection`

text
`tools.web`

text
`tools.media`

text
`tools.agentToAgent`

text
`tools.sessions`

text
`tools.sessions_spawn`

text
`tools.experimental`

text
`agents.defaults.subagents`