OpenClaw tools 配置和自定义 provider 设置指南。本页解决工具策略配置、白名单、实验性开关、自定义 provider 注册和 base URL 覆盖问题。关键操作：使用 tools.profile 设置基础白名单，tools.allow/deny 全局控制，byProvider 按模型限制，loopDetection 可启用工具循环检测。自定义 provider 通过 models.providers 配置，支持 openai-completions、anthropic-messages 等适配器。

OpenClaw tools 配置和自定义 provider 设置

Tools

工具配置项 (Tool profiles)

tools.profile 设置一个基础白名单，其后再由 tools.allow / tools.deny 进一步控制。

INFO

本地新配置在未设置 tools.profile 时，onboarding 默认设为 "coding"（已有显式 profile 的配置保持不变）。

Profile	包含的工具
`minimal`	仅 `session_status`
`coding`	`group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image`、`image_generate`、`video_generate`
`messaging`	`group:messaging`、`sessions_list`、`sessions_history`、`sessions_send`、`session_status`
`full`	无限制（等价于未设置）

工具分组 (Tool groups)

分组	包含的工具
`group:runtime`	`exec`、`process`、`code_execution`（`bash` 作为 `exec` 的别名接受）
`group:fs`	`read`、`write`、`edit`、`apply_patch`
`group:sessions`	`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status`
`group:memory`	`memory_search`、`memory_get`
`group:web`	`web_search`、`x_search`、`web_fetch`
`group:ui`	`browser`、`canvas`
`group:automation`	`heartbeat_respond`、`cron`、`gateway`
`group:messaging`	`message`
`group:nodes`	`nodes`
`group:agents`	`agents_list`、`update_plan`
`group:media`	`image`、`image_generate`、`music_generate`、`video_generate`、`tts`
`group:openclaw`	所有内置工具（不包括 provider 插件）
`group:plugins`	已加载插件拥有的工具，包括通过 `bundle-mcp` 暴露的 MCP 服务器

沙箱工具策略中的 MCP 和插件工具

配置的 MCP 服务器作为插件拥有的工具暴露，插件 id 为 bundle-mcp。普通工具 profile 允许它们，但 tools.sandbox.tools 是沙箱会话的额外关卡。如果沙箱模式为 "all" 或 "non-main"，要使 MCP/插件工具可见，需在沙箱工具白名单中包含以下条目之一：

bundle-mcp 用于 OpenClaw 管理的 mcp.servers 中的 MCP 服务器
具体原生插件的插件 id
group:plugins 用于所有已加载的插件属工具
精确的 MCP 服务器工具名或服务器 glob，如 outlook__send_mail 或 outlook__*，仅限单个服务器

服务器 glob 使用 provider-safe 的 MCP 服务器前缀，而非原始 mcp.servers 键。非 [A-Za-z0-9_-] 字符转为 -，不以字母开头的名称自动添加 mcp- 前缀，长前缀或重复前缀可能被截断或添加后缀。例如，mcp.servers["Outlook Graph"] 使用 glob 如 outlook-graph__*。

json5

{
  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"],
      },
    },
  },
}

没有这一沙箱层条目，MCP 服务器虽可成功加载，但其工具在发送 provider 请求之前已被过滤。使用 openclaw doctor 可检测 mcp.servers 中 OpenClaw 管理的服务器是否存在此问题。从捆绑插件清单或 Claude .mcp.json 加载的 MCP 服务器使用同样的沙箱门控，但该诊断尚未枚举这些来源；若它们的工具在沙箱轮次中消失，请使用相同的白名单条目。

`tools.allow` / `tools.deny`

全局工具允许/拒绝策略（拒绝优先）。不区分大小写，支持 * 通配符。即使 Docker 沙箱关闭也生效。

json5

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

write 和 apply_patch 是两个独立的工具 id。allow: ["write"] 也会为兼容模型启用 apply_patch，但 deny: ["write"] 不会拒绝 apply_patch。要阻止所有文件变更，请拒绝 group:fs 或逐个列出所有变更工具：

json5

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

`tools.byProvider`

针对特定 provider 或模型进一步限制工具。顺序：基础 profile → provider profile → allow/deny。

json5

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

`tools.toolsBySender`

针对特定请求者身份限制工具。这是渠道访问控制之上的深度防御；发送者值必须来自渠道适配器，而非消息文本。

json5

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

键使用显式前缀：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName> 或 "*"。渠道 id 是 OpenClaw 的规范 id；别名如 teams 会归一化为 msteams。无前缀的旧版键仅作为 id: 接受。匹配顺序：channel+id、id、e164、username、name，最后通配符。

每个智能体的 agents.list[].tools.toolsBySender 会在匹配时覆盖全局的发送者匹配，即使策略为空 {}。

`tools.elevated`

控制沙箱外的提升 exec 访问：

json5

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

智能体级别覆盖（agents.list[].tools.elevated）只能进一步限制，不能放宽。
/elevated on|off|ask|full 按会话存储状态；内联指令仅对单条消息生效。
提升后的 exec 绕过沙箱，使用配置的逃逸路径（默认 gateway，当 exec 目标为 node 时则为 node）。

`tools.exec`

json5

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

`tools.loopDetection`

工具循环安全检查默认禁用。设置 enabled: true 激活检测。可在全局 tools.loopDetection 定义，并在智能体级别通过 agents.list[].tools.loopDetection 覆盖。

json5

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

historySize number

循环分析保留的最大工具调用历史数。

warningThreshold number

重复无进展模式的警告阈值。

criticalThreshold number

更高的重复阈值，用于阻止严重循环。

globalCircuitBreakerThreshold number

任何无进展运行的硬停止阈值。

detectors.genericRepeat boolean

对重复相同工具/相同参数的调用发出警告。

detectors.knownPollNoProgress boolean

对已知轮询工具（process.poll、command_status 等）警告/阻止。

detectors.pingPong boolean

对交替无进展对模式警告/阻止。

WARNING

如果 warningThreshold >= criticalThreshold 或 criticalThreshold >= globalCircuitBreakerThreshold，验证失败。

`tools.web`

json5

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // 或使用环境变量 BRAVE_API_KEY
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl", // 可选，省略时自动检测
        maxChars: 50000,
        maxCharsCap: 50000,
        maxResponseBytes: 2000000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        userAgent: "custom-ua",
      },
    },
  },
}

`tools.media`

配置入站媒体理解（图片/音频/视频）：

json5

{
  tools: {
    media: {
      concurrency: 2,
      asyncCompletion: {
        directSend: false, // 已弃用：补全保持智能体中介
      },
      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", "&#123;&#123;MediaPath&#125;&#125;"] },
        ],
      },
      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" }],
      },
    },
  },
}

媒体模型条目字段

**Provider 条目**（`type: "provider"` 或省略）：

- `provider`：API provider id（`openai`、`anthropic`、`google`/`gemini`、`groq` 等）
- `model`：模型 id 覆盖
- `profile` / `preferredProfile`：`auth-profiles.json` 的配置文件选择

**CLI 条目**（`type: "cli"`）：

- `command`：要运行的可执行文件
- `args`：带模板的参数（支持 `&#123;&#123;MediaPath&#125;&#125;`、`&#123;&#123;Prompt&#125;&#125;`、`&#123;&#123;MaxChars&#125;&#125;` 等；`openclaw doctor --fix` 会迁移已弃用的 `{input}` 占位符到 `&#123;&#123;MediaPath&#125;&#125;`）

**共有字段：**

- `capabilities`：可选的列表（`image`、`audio`、`video`）。默认：`openai`/`anthropic`/`minimax` → 图片，`google` → 图片+音频+视频，`groq` → 音频。
- `prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`：每个条目的覆盖值。
- `tools.media.image.timeoutSeconds` 以及匹配图片模型条目的 `timeoutSeconds` 同样适用于智能体调用显式 `image` 工具时。
- 失败时会回退到下一个条目。

Provider 认证遵循标准顺序：`auth-profiles.json` → 环境变量 → `models.providers.*.apiKey`。

**异步补全字段：**

- `asyncCompletion.directSend`：已弃用的兼容性标志。完成的异步媒体任务保持请求者会话中介，因此智能体接收结果，决定如何告知用户，并在需要源投递时使用消息工具。

`tools.agentToAgent`

json5

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

`tools.sessions`

控制哪些会话可以被会话工具（sessions_list、sessions_history、sessions_send）访问。

默认值：tree（当前会话 + 由其衍生的会话，如子智能体）。

json5

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

可见性范围

- `self`：仅当前会话键。
- `tree`：当前会话 + 由当前会话衍生的会话（子智能体）。
- `agent`：属于当前智能体 id 的任何会话（如果对同一智能体 id 运行逐发送者会话，可能包含其他用户）。
- `all`：任何会话。跨智能体定位仍需 `tools.agentToAgent`。
- 沙箱夹紧：当前会话被沙箱化且 `agents.defaults.sandbox.sessionToolsVisibility="spawned"` 时，即使 `tools.sessions.visibility="all"`，可见性也会被强制设为 `tree`。

`tools.sessions_spawn`

控制 sessions_spawn 的内联附件支持。

json5

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // 需主动开启：设为 true 允许内联文件附件
        maxTotalBytes: 5242880, // 所有文件总计 5 MB
        maxFiles: 50,
        maxFileBytes: 1048576, // 每个文件 1 MB
        retainOnSessionKeep: false, // 当 cleanup="keep" 时保留附件
      },
    },
  },
}

附件说明

- 附件仅支持 `runtime: "subagent"`。ACP 运行时会拒绝附件。
- 文件会被物化到子工作区 `.openclaw/attachments/&lt;uuid&gt;/` 中，并附带 `.manifest.json`。
- 附件内容自动从记录持久化中编辑（redacted）。
- Base64 输入经过严格字符/填充校验以及解码前大小检查。
- 文件权限：目录 `0700`，文件 `0600`。
- 清理遵循 `cleanup` 策略：`delete` 总是移除附件；`keep` 仅在 `retainOnSessionKeep: true` 时保留。

`tools.experimental`

实验性内置工具开关。默认关闭，除非 strict-agentic GPT-5 自动启用规则适用。

json5

{
  tools: {
    experimental: {
      planTool: true, // 启用实验性 update_plan
    },
  },
}

planTool：启用结构化的 update_plan 工具，用于非平凡的多步骤工作追踪。
默认：false，除非 agents.defaults.embeddedPi.executionContract（或每个智能体的覆盖）对于 OpenAI 或 OpenAI Codex GPT-5 系列运行设为 "strict-agentic"。设为 true 强制在该范围外启用，设为 false 即使 strict-agentic GPT-5 运行也保持关闭。
启用时，系统提示还会添加使用指南，使模型仅在必要工作时使用该工具，并保持最多一个步骤 in_progress。

`agents.defaults.subagents`

json5

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

model：衍生子智能体的默认模型。省略时子智能体继承调用者的模型。
allowAgents：当请求者智能体未设置自己的 subagents.allowAgents 时，sessions_spawn 的默认已配置目标智能体 id 白名单（["*"] = 任何已配置的目标；默认：仅同一智能体）。已删除智能体配置的陈旧条目会被 sessions_spawn 拒绝并从 agents_list 中省略；运行 openclaw doctor --fix 清理它们。
runTimeoutSeconds：当工具调用省略 runTimeoutSeconds 时 sessions_spawn 的默认超时（秒）。0 表示无超时。
announceTimeoutMs：每次 Gateway agent 公告投递尝试的超时（毫秒）。默认 120000。重试可能使总公告等待时间超过一个配置的超时。
每个子智能体的工具策略：tools.subagents.tools.allow / tools.subagents.tools.deny。

自定义 provider 和 base URL

OpenClaw 使用内置模型目录。通过配置中的 models.providers 或 ~/.openclaw/agents/<agentId>/agent/models.json 添加自定义 provider。

配置自定义/本地 provider baseUrl 也构成了模型 HTTP 请求的狭域网络信任决策：OpenClaw 允许该精确的 scheme://host:port 源通过受保护的 fetch 路径，无需额外配置选项或信任其他私有源。

json5

{
  models: {
    mode: "merge", // merge（默认） | 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,
          },
        ],
      },
    },
  },
}

认证和合并优先级

- 使用 `authHeader: true` + `headers` 满足自定义认证需求。
- 通过 `OPENCLAW_AGENT_DIR`（或旧环境变量别名 `PI_CODING_AGENT_DIR`）覆盖智能体配置根目录。
- 对于匹配 provider id 的合并优先级：
  - 非空智能体 `models.json` 的 `baseUrl` 值优先。
  - 非空智能体 `apiKey` 值仅当该 provider 在当前配置/auth-profile 上下文中未由 SecretRef 管理时优先。
  - SecretRef 管理的 provider `apiKey` 值从源标记（`ENV_VAR_NAME` 用于 env 引用，`secretref-managed` 用于文件/exec 引用）刷新，而非持久化已解析的秘密。
  - SecretRef 管理的 provider header 值从源标记刷新（`secretref-env:ENV_VAR_NAME` 用于 env 引用，`secretref-managed` 用于文件/exec 引用）。
  - 空或缺失的智能体 `apiKey`/`baseUrl` 回退到 `models.providers` 中的配置。
  - 匹配模型的 `contextWindow`/`maxTokens` 使用显式配置与隐式目录值中的较大者。
  - 匹配模型的 `contextTokens` 在存在时保留显式运行时上限；用于在不更改原生模型元数据的情况下限制有效上下文。
  - 使用 `models.mode: "replace"` 让配置完全重写 `models.json`。
  - 标记持久化是源权威的：标记从活动源配置快照（解析前）写入，而非解析后的运行时秘密值。

Provider 字段详情

顶层目录

- `models.mode`：provider 目录行为（`merge` 或 `replace`）。
- `models.providers`：按 provider id 键化的自定义 provider 映射。
  - 安全编辑：使用 `openclaw config set models.providers.&lt;id&gt; '&lt;json&gt;' --strict-json --merge` 或 `openclaw config set models.providers.&lt;id&gt;.models '&lt;json-array&gt;' --strict-json --merge` 进行增量更新。`config set` 拒绝破坏性替换，除非传递 `--replace`。

Provider 连接和认证

- `models.providers.*.api`：请求适配器（`openai-completions`、`openai-responses`、`anthropic-messages`、`google-generative-ai` 等）。对于自托管 `/v1/chat/completions` 后端（如 MLX、vLLM、SGLang 和大多数兼容 OpenAI 的本地服务器），使用 `openai-completions`。拥有 `baseUrl` 但未设置 `api` 的自定义 provider 默认使用 `openai-completions`；仅当后端支持 `/v1/responses` 时才设置 `openai-responses`。
- `models.providers.*.apiKey`：provider 凭证（优先使用 SecretRef/环境变量替换）。
- `models.providers.*.auth`：认证策略（`api-key`、`token`、`oauth`、`aws-sdk`）。
- `models.providers.*.contextWindow`：此 provider 下模型条目未设置 `contextWindow` 时的默认原生上下文窗口。
- `models.providers.*.contextTokens`：此 provider 下模型条目未设置 `contextTokens` 时的默认有效运行时上下文上限。
- `models.providers.*.maxTokens`：此 provider 下模型条目未设置 `maxTokens` 时的默认输出 token 上限。
- `models.providers.*.timeoutSeconds`：可选的每个 provider 模型 HTTP 请求超时（秒），包括连接、头部、正文和总请求终止处理。
- `models.providers.*.injectNumCtxForOpenAICompat`：对于 Ollama + `openai-completions`，将 `options.num_ctx` 注入请求（默认 `true`）。
- `models.providers.*.authHeader`：当需要时强制在 `Authorization` 头部传输凭证。
- `models.providers.*.baseUrl`：上游 API 基础 URL。
- `models.providers.*.headers`：用于代理/租户路由的额外静态头部。

请求传输覆盖

`models.providers.*.request`：模型 provider HTTP 请求的传输覆盖。

- `request.headers`：额外头部（与 provider 默认头部合并）。值接受 SecretRef。
- `request.auth`：认证策略覆盖。模式：`"provider-default"`（使用 provider 内置认证）、`"authorization-bearer"`（带 `token`）、`"header"`（带 `headerName`、`value`、可选 `prefix`）。
- `request.proxy`：HTTP 代理覆盖。模式：`"env-proxy"`（使用 `HTTP_PROXY`/`HTTPS_PROXY` 环境变量）、`"explicit-proxy"`（带 `url`）。两种模式均接受可选的 `tls` 子对象。
- `request.tls`：直接连接的 TLS 覆盖。字段：`ca`、`cert`、`key`、`passphrase`（均接受 SecretRef）、`serverName`、`insecureSkipVerify`。
- `request.allowPrivateNetwork`：当为 `true` 时，允许模型 provider HTTP 请求访问私有、CGNAT 或类似范围，绕过 provider HTTP fetch 守卫。自定义/本地 provider base URL 已经信任精确配置的源，但元数据/链路本地源仍被阻止，除非显式选择。设为 `false` 可退出精确源信任。WebSocket 使用相同的 `request` 用于头部/TLS，但不使用该 fetch SSRF 门。默认为 `false`。

模型目录条目

- `models.providers.*.models`：显式 provider 模型目录条目。
- `models.providers.*.models.*.input`：模型输入模态。对于仅文本模型使用 `["text"]`，对于原生图像/视觉模型使用 `["text", "image"]`。仅当所选模型标记为支持图像时，图像附件才会注入到智能体轮次中。
- `models.providers.*.models.*.contextWindow`：原生模型上下文窗口元数据。这会覆盖该模型的 provider 级别 `contextWindow`。
- `models.providers.*.models.*.contextTokens`：可选的运行时上下文上限。这会覆盖 provider 级别的 `contextTokens`；当你想使用比模型原生 `contextWindow` 更小的有效上下文预算时使用；`openclaw models list` 会在两者不同时显示。
- `models.providers.*.models.*.compat.supportsDeveloperRole`：可选的兼容性提示。对于 `api: "openai-completions"` 且具有非空非原生 `baseUrl`（主机不是 `api.openai.com`），OpenClaw 运行时会强制设为 `false`。空/省略的 `baseUrl` 保持默认 OpenAI 行为。
- `models.providers.*.models.*.compat.requiresStringContent`：可选的兼容性提示，用于仅字符串的 OpenAI 兼容聊天端点。当为 `true` 时，OpenClaw 会在发送请求前将纯文本 `messages[].content` 数组展平为简单字符串。
- `models.providers.*.models.*.compat.strictMessageKeys`：可选的兼容性提示，用于严格的 OpenAI 兼容聊天端点。当为 `true` 时，OpenClaw 会在发送请求前将传出 Chat Completions 消息对象缩减为 `role` 和 `content`。
- `models.providers.*.models.*.compat.thinkingFormat`：可选的思考负载提示。使用 `"together"` 表示 Together 风格的 `reasoning.enabled`，`"qwen"` 表示顶层 `enable_thinking`，或 `"qwen-chat-template"` 表示 Qwen 家族 OpenAI 兼容服务器上的 `chat_template_kwargs.enable_thinking`（例如 vLLM）。

Amazon Bedrock 发现

- `plugins.entries.amazon-bedrock.config.discovery`：Bedrock 自动发现设置根。
- `plugins.entries.amazon-bedrock.config.discovery.enabled`：打开/关闭隐式发现。
- `plugins.entries.amazon-bedrock.config.discovery.region`：发现的 AWS 区域。
- `plugins.entries.amazon-bedrock.config.discovery.providerFilter`：可选的 provider-id 过滤器，用于针对性发现。
- `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`：发现刷新的轮询间隔。
- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`：发现模型的回退上下文窗口。
- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`：发现模型的回退最大输出 token。

交互式自定义 provider onboarding 会为常见视觉模型 ID（如 GPT-4o、Claude、Gemini、Qwen-VL、LLaVA、Pixtral、InternVL、Mllama、MiniCPM-V、GLM-4V）推断图像输入，并跳过对已知纯文本家族的额外询问。未知模型 ID 仍会提示是否支持图像。非交互式 onboarding 使用相同的推断；传递 --custom-image-input 强制图像能力元数据，或 --custom-text-input 强制纯文本元数据。

Provider 示例

Cerebras (GLM 4.7 / GPT OSS)

捆绑的 `cerebras` provider 插件可以通过 `openclaw onboard --auth-choice cerebras-api-key` 配置此项。仅在需要覆盖默认值时使用显式 provider 配置。

```json5
{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/gpt-oss-120b"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/gpt-oss-120b": { alias: "GPT OSS 120B (Cerebras)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "gpt-oss-120b", name: "GPT OSS 120B (Cerebras)" },
        ],
      },
    },
  },
}
```

对于 Cerebras 使用 `cerebras/zai-glm-4.7`；对于 Z.AI 直接使用 `zai/glm-4.7`。

Kimi Coding

```json5
{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi/kimi-for-coding" },
      models: { "kimi/kimi-for-coding": { alias: "Kimi Code" } },
    },
  },
}
```

兼容 Anthropic，内置 provider。快捷方式：`openclaw onboard --auth-choice kimi-code-api-key`。

本地模型 (LM Studio)

参见 [本地模型](/ai/ai-tools/openclaw/gateway/local-models)。简而言之：在强大硬件上通过 LM Studio Responses API 运行大型本地模型；保持托管模型合并用于回退。

MiniMax M2.7 (直接)

```json5
{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.7" },
      models: {
        "minimax/MiniMax-M2.7": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.7",
            name: "MiniMax M2.7",
            reasoning: true,
            input: ["text"],
            cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
            contextWindow: 204800,
            maxTokens: 131072,
          },
        ],
      },
    },
  },
}
```

设置 `MINIMAX_API_KEY`。快捷方式：`openclaw onboard --auth-choice minimax-global-api` 或 `openclaw onboard --auth-choice minimax-cn-api`。模型目录默认仅有 M2.7。在兼容 Anthropic 的流式路径上，OpenClaw 默认禁用 MiniMax 思考，除非显式设置 `thinking`。`/fast on` 或 `params.fastMode: true` 会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。

Moonshot AI (Kimi)

```json5
{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.6" },
      models: { "moonshot/kimi-k2.6": { alias: "Kimi K2.6" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.6",
            name: "Kimi K2.6",
            reasoning: false,
            input: ["text", "image"],
            cost: { input: 0.95, output: 4, cacheRead: 0.16, cacheWrite: 0 },
            contextWindow: 262144,
            maxTokens: 262144,
          },
        ],
      },
    },
  },
}
```

中国端点：`baseUrl: "https://api.moonshot.cn/v1"` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`。

原生 Moonshot 端点在共享的 `openai-completions` 传输上公告流式使用兼容性，OpenClaw 根据端点能力（而非内置 provider id 本身）对其进行键控。

OpenCode

```json5
{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}
```

设置 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）。对于 Zen 目录使用 `opencode/...` 引用，对于 Go 目录使用 `opencode-go/...` 引用。快捷方式：`openclaw onboard --auth-choice opencode-zen` 或 `openclaw onboard --auth-choice opencode-go`。

Synthetic (兼容 Anthropic)

```json5
{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}
```

Base URL 应省略 `/v1`（Anthropic 客户端会追加）。快捷方式：`openclaw onboard --auth-choice synthetic-api-key`。

Z.AI (GLM-4.7)

```json5
{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}
```

设置 `ZAI_API_KEY`。`z.ai/*` 和 `z-ai/*` 被接受为别名。快捷方式：`openclaw onboard --auth-choice zai-api-key`。

- 通用端点：`https://api.z.ai/api/paas/v4`
- 编码端点（默认）：`https://api.z.ai/api/coding/paas/v4`
- 对于通用端点，定义自定义 provider 并覆盖 base URL。

常见问题

怎么设置 tools 白名单？自定义允许/拒绝的工具？

使用 tools.profile 设置基础白名单（可选 minimal、coding、messaging、full），再通过 tools.allow / tools.deny 进一步细粒度控制。拒绝优先。例如 tools: { deny: ["browser", "canvas"] } 禁用这两种工具。按模型或发送者限制可使用 tools.byProvider 和 tools.toolsBySender。

怎么添加自定义 provider，比如本地 LLM（vLLM、Ollama）？

在 models.providers 中添加 provider 条目，设置 baseUrl（如 http://localhost:8000/v1），api 设为 openai-completions，并列出支持的模型。OpenClaw 默认信任该精确 scheme://host:port 源。使用 openclaw onboard 交互式向导可以简化配置，对于本地模型建议通过 --custom-image-input 指定图片能力。

tools.loopDetection 怎么启用？有什么阈值需要配置？

默认禁用。在 tools.loopDetection 中设置 enabled: true 即可。常用阈值：warningThreshold: 10、criticalThreshold: 20、globalCircuitBreakerThreshold: 30。注意必须 warningThreshold < criticalThreshold < globalCircuitBreakerThreshold，否则验证失败。还可开启 genericRepeat、knownPollNoProgress、pingPong 等检测器。

OpenClaw tools 配置和自定义 provider 设置 ​

Tools ​

工具配置项 (Tool profiles) ​

工具分组 (Tool groups) ​

沙箱工具策略中的 MCP 和插件工具 ​

tools.allow / tools.deny ​

tools.byProvider ​

tools.toolsBySender ​

tools.elevated ​

tools.exec ​

tools.loopDetection ​

tools.web ​

tools.media ​

tools.agentToAgent ​

tools.sessions ​

tools.sessions_spawn ​

tools.experimental ​

agents.defaults.subagents ​

自定义 provider 和 base URL ​

Provider 字段详情 ​

Provider 示例 ​

相关文档 ​

常见问题 ​

怎么设置 tools 白名单？自定义允许/拒绝的工具？ ​

怎么添加自定义 provider，比如本地 LLM（vLLM、Ollama）？ ​

tools.loopDetection 怎么启用？有什么阈值需要配置？ ​

OpenClaw tools 配置和自定义 provider 设置

Tools

工具配置项 (Tool profiles)

工具分组 (Tool groups)

沙箱工具策略中的 MCP 和插件工具

`tools.allow` / `tools.deny`

`tools.byProvider`

`tools.toolsBySender`

`tools.elevated`

`tools.exec`

`tools.loopDetection`

`tools.web`

`tools.media`

`tools.agentToAgent`

`tools.sessions`

`tools.sessions_spawn`

`tools.experimental`

`agents.defaults.subagents`

自定义 provider 和 base URL

Provider 字段详情

Provider 示例

相关文档

常见问题

怎么设置 tools 白名单？自定义允许/拒绝的工具？

怎么添加自定义 provider，比如本地 LLM（vLLM、Ollama）？

tools.loopDetection 怎么启用？有什么阈值需要配置？