OpenClaw openclaw.json 配置说明

1. 文档定位

这份文档用于说明 OpenClaw 的主配置文件 openclaw.json（实际支持 JSON5 语法）中有哪些配置块、每个配置块有哪些常见参数、每个参数的作用，以及配置时需要特别注意的行为。

• 默认配置路径：~/.openclaw/openclaw.json
• 文件格式：JSON5（支持注释、尾逗号、非严格引号键名）
• 校验特性：严格按 schema 校验；未知字段、错误类型、非法值都会导致 Gateway 拒绝启动
• 建议排错命令：openclaw doctor、openclaw doctor --fix
• 推荐修改方式：openclaw configure、openclaw config get/set/unset ...、控制台 UI 的 Config 页、或直接编辑文件

说明：本说明以 OpenClaw 官方文档与 src/config/types.openclaw.ts、src/config/types.tools.ts、src/config/schema.help.ts 为依据整理，重点对 tools 章节做了展开。

2. 配置文件的几个核心规则

2.1 JSON5 不是普通 JSON

你可以这样写：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
  },
}

这意味着：

• 可以写注释
• 可以保留尾逗号
• 键名不一定都要加引号

2.2 配置校验非常严格

OpenClaw 不是“有错就忽略”，而是“有错就不启动”。

常见导致启动失败的情况：

• 写了 schema 中不存在的字段
• 字段类型不对，例如布尔值写成字符串
• 枚举值写错，例如只允许 allowlist，却写成了 allow-list

2.3 支持环境变量替换

可以在字符串里写 ${ENV_NAME}：

{
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

规则：

• 只匹配大写环境变量名：[A-Z_][A-Z0-9_]*
• 环境变量不存在或为空时会报错
• $${VAR} 表示输出字面量 ${VAR}

2.4 支持 $include 拆分配置

适合把大配置拆成多文件：

{
  agents: { $include: "./agents.json5" },
  broadcast: { $include: ["./client-a.json5", "./client-b.json5"] },
}

适用场景：

• 多智能体配置较大
• 想把客户配置分开
• 想把通用配置与环境差异配置拆开

3. 顶层配置总览

以下是 openclaw.json 已确认的顶层配置块：

4. 各顶层配置块说明

这一节按“顶层键”展开，帮助你快速知道每一块是做什么的、应重点看哪些参数。

4.0 $schema

这是根级的 schema 元数据字段。

作用：

• 方便编辑器识别配置文件 schema
• 不参与业务逻辑配置
• 在严格校验场景下，它是官方明确允许的根级特殊字段

4.1 meta

系统维护的元信息，通常不建议手动编辑。

• meta.lastTouchedVersion：最近一次写入该配置文件的 OpenClaw 版本
• meta.lastTouchedAt：最近一次写入时间（ISO 时间戳）

4.2 auth

用于维护认证配置文件的元数据映射，不直接存储 API 密钥本体。

常见参数：

• auth.profiles：认证配置文件字典；把 profile id 映射到 provider / mode / email
• auth.order：同一 provider 下多个 profile 的使用顺序

示例：

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}

4.3 acp

用于 ACP 运行时的启用、默认后端、允许代理、流式投影与并发控制。

常见参数：

• acp.enabled：是否启用 ACP
• acp.dispatch.enabled：是否允许 ACP session turn 调度
• acp.backend：默认 ACP 后端 id
• acp.defaultAgent：未显式指定时的默认目标 agent
• acp.allowedAgents：允许被 ACP 选中的 agent 白名单
• acp.maxConcurrentSessions：并发会话上限
• acp.stream.*：流式投影块大小、去重、可见性等

4.4 env

控制环境变量如何注入 Gateway 进程。

常见参数：

• env.shellEnv.enabled：是否从登录 shell 读取环境变量
• env.shellEnv.timeoutMs：读取 shell 环境的超时
• env.vars：显式注入的环境变量字典
• env.<KEY>：也支持直接在 env 下写字符串键值作为简写

适合场景：

• OpenClaw 作为服务运行，进程环境不完整
• 模型密钥在 shell profile 或 .env 中，需要补读

4.5 wizard

记录最近一次向导执行的元数据，主要用于可观测性和排查。

常见参数：

• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode：local 或 remote

4.6 diagnostics

诊断专用。

常见参数：

• diagnostics.otel：OpenTelemetry 输出
• diagnostics.cacheTrace：缓存命中/回退追踪

4.7 logging

控制日志级别、格式、落盘路径与敏感信息脱敏。

常见参数：

• logging.level：主日志级别
• logging.file：日志文件路径
• logging.consoleLevel：控制台日志级别
• logging.consoleStyle：pretty / compact / json
• logging.redactSensitive：是否对敏感工具/配置内容脱敏
• logging.redactPatterns：自定义脱敏正则列表

4.8 cli

主要是 CLI 外观与启动横幅表现。

常见参数：

• cli.banner
• cli.banner.taglineMode：random / default / off

4.9 update

用于控制版本通道和自动更新策略。

常见参数：

• update.channel：stable / beta / dev
• update.checkOnStart：启动时检查更新
• update.auto.enabled：后台自动更新
• update.auto.stableDelayHours
• update.auto.stableJitterHours
• update.auto.betaCheckIntervalHours

4.10 browser

控制浏览器能力的启用方式、CDP 连接、Profile、快照、SSRF 防护等。

常见参数：

• browser.enabled
• browser.cdpUrl
• browser.executablePath
• browser.headless
• browser.noSandbox
• browser.attachOnly
• browser.defaultProfile
• browser.profiles.*
• browser.snapshotDefaults.*
• browser.ssrfPolicy.*

适合场景：

• 要用浏览器工具访问网页、登录站点、截图
• 需要连接已有 Chrome/Chromium 进程

4.11 ui

控制 UI 的视觉信息。

常见参数：

• ui.seamColor：UI 强调色
• ui.assistant.name：UI 中显示的助手名称
• ui.assistant.avatar：UI 使用的头像

4.12 secrets

与密钥来源、秘密输入引用等相关。此块更多依赖 OpenClaw 的 secrets 子系统，通常配合环境变量、secret ref 或 configure 向导使用。

4.13 skills

用于 Skill 系统配置，例如技能入口、密钥、暴露方式等。具体字段会随 Skills 实现变化。

4.14 plugins

插件系统配置。用于启用插件、传入插件参数、为扩展渠道提供配置。

4.15 models

控制模型 provider、主模型、回退模型、路由与 API 密钥。

常见关注点：

• 配置不同 provider 的 apiKey
• 配置主模型与 fallbacks
• 控制 provider/baseUrl 的自定义接入

4.16 nodeHost

用于节点主机和多节点执行相关配置，常与 tools.exec.host = "node" 搭配。

它的价值在于：

• 让 shell / exec 工具不在当前 gateway 上执行
• 把执行委派给已连接节点

4.17 agents

这是 OpenClaw 的核心配置块之一，用于定义智能体默认值、多个 agent 列表、工作区、模型、沙箱、身份、工具限制等。

常见参数：

• agents.defaults：所有 agent 共用默认值
• agents.list[]：显式列出每个 agent

常见子参数（尤其重要）：

• agents.defaults.workspace
• agents.defaults.repoRoot
• agents.defaults.skipBootstrap
• agents.defaults.bootstrapMaxChars
• agents.defaults.userTimezone
• agents.defaults.timeFormat
• agents.defaults.model
• agents.defaults.sandbox
• agents.list[].id
• agents.list[].default
• agents.list[].workspace
• agents.list[].agentDir
• agents.list[].model
• agents.list[].identity
• agents.list[].groupChat
• agents.list[].sandbox
• agents.list[].tools
• agents.list[].subagents

4.18 tools

tools 是本文重点，下一章单独详细展开。

4.19 bindings

控制入站消息如何路由到不同 agent。

常见参数：

• bindings[].agentId：命中的消息应交给哪个 agent
• bindings[].match.channel：渠道条件
• bindings[].match.accountId：账号条件
• bindings[].match.peer：点对点对象条件
• bindings[].match.guildId / match.teamId：平台特定条件

4.20 broadcast

用于定义广播消息与目标组映射，适合“一个入口对多个 agent / 频道做同步发送”之类的场景。

4.21 audio

与音频处理能力有关，通常和语音、媒体处理链路联动。

4.22 media

控制媒体文件存储行为。

常见参数：

• media.preserveFilenames：保留原始上传文件名
• media.ttlHours：媒体文件保留时长

4.23 messages

用于控制入站/出站消息的外观、节流、队列、群聊上下文。

常见参数：

• messages.responsePrefix
• messages.ackReaction
• messages.ackReactionScope
• messages.removeAckAfterReply
• messages.queue.*
• messages.inbound.*
• messages.groupChat.historyLimit
• messages.tts.*

4.24 commands

控制聊天命令系统是否启用、如何启用。

常见参数：

• commands.native
• commands.text
• commands.bash
• commands.bashForegroundMs
• commands.config
• commands.debug
• commands.restart
• commands.useAccessGroups

4.25 approvals

与审批、确认、人机授权流程相关，通常会影响高风险操作是否需要用户确认。

4.26 session

控制会话生命周期、上下文压缩、保留策略、会话工具可见性等。

4.27 web

这是 渠道级 Web 运行时，不要和 tools.web 混淆。

常见参数：

• web.enabled
• web.heartbeatSeconds
• web.reconnect.initialMs
• web.reconnect.maxMs
• web.reconnect.factor
• web.reconnect.jitter
• web.reconnect.maxAttempts

4.28 channels

用于配置聊天渠道。常见已知渠道包括：

• channels.whatsapp
• channels.telegram
• channels.discord
• channels.googlechat
• channels.slack
• channels.mattermost
• channels.signal
• channels.imessage
• 以及其它扩展渠道

这些渠道通常会反复出现以下模式：

• enabled：是否启用该渠道
• accounts：多账号
• dmPolicy / policy：私聊策略
• allowFrom：允许触发的用户
• groupPolicy：群组是否允许
• groups / guilds / channels：群组/频道白名单与局部覆盖
• actions：是否开放反应、发消息、线程、权限等动作
• historyLimit：附带的历史上下文条数
• mediaMaxMb：媒体大小限制
• configWrites：是否允许该渠道触发配置写入

4.29 cron

用于定时任务。

通常会定义：

• 任务何时触发
• 触发后发送到哪个 agent / channel
• 运行什么动作

4.30 hooks

用于在某些事件或阶段挂接逻辑。

常见关注点：

• hooks.mappings[]
• 不同事件对应的变换、思考、转发或副作用处理

4.31 discovery

服务发现配置。

常见参数：

• discovery.mdns.mode
• discovery.wideArea.enabled

4.32 canvasHost

控制 Canvas 资源托管服务。

常见参数：

• canvasHost.enabled
• canvasHost.root
• canvasHost.port
• canvasHost.liveReload

4.33 talk

面向语音模式、TTS、打断控制。

常见参数：

• talk.provider
• talk.providers.*
• talk.providers.*.voiceId
• talk.providers.*.voiceAliases
• talk.providers.*.modelId
• talk.providers.*.outputFormat
• talk.providers.*.apiKey
• talk.interruptOnSpeech
• talk.silenceTimeoutMs

4.34 gateway

Gateway 是 OpenClaw 的另一个超核心配置块，负责监听、身份认证、Control UI、远程连接、TLS、HTTP 兼容端点等。

常见参数：

• gateway.port
• gateway.mode
• gateway.bind
• gateway.customBindHost
• gateway.controlUi.*
• gateway.auth.*
• gateway.trustedProxies
• gateway.allowRealIpFallback
• gateway.tools.*
• gateway.channelHealthCheckMinutes
• gateway.tailscale.*
• gateway.remote.*
• gateway.reload.*
• gateway.tls.*
• gateway.http.endpoints.*

4.35 memory

与向量记忆搜索、索引、同步、查询、缓存相关。

常见关注点：

• provider：使用哪个 embedding provider
• remote.*：远端 embedding 服务与 API key
• store.*：索引存储驱动和路径
• chunking.*：切块策略
• sync.*：什么时候增量索引
• query.*：召回、最低分、混合检索

5. tools 详细说明（重点）

tools 是 OpenClaw 中最容易配错、也最值得重点理解的一块。它既控制“有哪些工具可用”，也控制“工具怎么跑、在哪里跑、哪些人能触发、遇到循环时怎么办”。

5.1 tools 的整体结构

根据当前类型定义，tools 下已确认包含：

{
  tools: {
    profile: "coding",
    allow: [],
    alsoAllow: [],
    deny: [],
    byProvider: {},
    web: { search: {}, fetch: {} },
    media: {},
    links: {},
    message: {},
    agentToAgent: {},
    sessions: {},
    elevated: {},
    exec: {},
    fs: {},
    loopDetection: {},
    subagents: {},
    sandbox: {},
  },
}

5.2 tools 的配置优先级怎么理解

这是配置 tools 时最重要的部分。

基础顺序

1. profile：先给出一组基础工具策略
2. allow：绝对白名单，通常用于替代 profile 派生默认值
3. alsoAllow：在已有白名单基础上追加允许项
4. deny：最终禁止项，优先级最高，即使前面允许了也会被挡掉
5. byProvider：按模型 provider 或 provider/model 做局部覆盖
6. agents.list[].tools：可对单个 agent 再做覆写或收紧

实践建议

• 想“整体收紧”：优先用 allow + deny
• 想“在默认基础上只多开一两个工具”：优先用 alsoAllow
• 想“某个 provider 能用某工具，另一个 provider 不能用”：用 byProvider
• 想“主 agent 和子 agent 工具能力不同”：分别用 tools.subagents 和 agents.list[].tools

5.3 tools.profile

类型："minimal" | "coding" | "messaging" | "full"

作用：

• 定义一组预置的基础工具策略
• 相当于“工具能力模板”

建议：

• minimal：最保守
• coding：适合代码修改、文件读写、exec 等开发场景
• messaging：偏消息与渠道交互
• full：开放能力最多

5.4 tools.allow

类型：string[]

作用：

• 绝对白名单
• 用它可以明确指定只允许哪些工具

适合场景：

• 要做强约束环境
• 要面向公众暴露某个 agent，但只允许少量安全工具

5.5 tools.alsoAllow

类型：string[]

作用：

• 在既有允许集基础上追加工具
• 比直接写 allow 更适合“只加一点”

适合场景：

• 你已经有一个合适的 profile
• 只想额外开放 lobster、web_fetch 之类的单个能力

5.6 tools.deny

类型：string[]

作用：

• 全局拒绝名单
• 即使某工具被 profile / allow / alsoAllow 放开，也会被 deny 最终挡掉

最常见用途：

• 临时封禁 exec
• 临时封禁 browser
• 临时封禁高风险写文件工具

5.7 tools.byProvider

类型：Record<string, ToolPolicyConfig>

作用：

• 针对 provider 级别或 provider/model 级别单独定义工具策略

可配子参数：

• allow
• alsoAllow
• deny
• profile

适用例子：

• openai/* 可以用 apply_patch
• 某些 provider 只能读文件、不能 exec

6. tools.web：网页搜索与网页抓取

tools.web 分成两大块：

• tools.web.search：搜索
• tools.web.fetch：抓取网页正文

6.1 tools.web.search

作用：控制 web_search 工具。

已确认参数

Provider 级子配置

tools.web.search.brave

• mode: "web" | "llm-context"
  • web：标准网页搜索结果
  • llm-context：偏向直接为 LLM 准备上下文

tools.web.search.gemini

• apiKey：Gemini API key，也可回退到 GEMINI_API_KEY
• model：搜索/grounded search 使用的模型，默认常见值为 gemini-2.5-flash

tools.web.search.grok

• apiKey：xAI API key，也可回退到 XAI_API_KEY
• model：Grok 搜索模型
• inlineCitations：是否在结果正文中内联 markdown 引用

tools.web.search.kimi

• apiKey：Kimi / Moonshot API key，可回退到 KIMI_API_KEY 或 MOONSHOT_API_KEY
• baseUrl：Kimi API 基础地址，默认常见值为 https://api.moonshot.ai/v1
• model：Kimi 搜索模型

tools.web.search.perplexity

• apiKey：Perplexity API key，可回退到 PERPLEXITY_API_KEY
• baseUrl：已标为 legacy / deprecated，对 Search API 忽略
• model：已标为 legacy / deprecated，对 Search API 忽略

自动探测顺序

官方文档已明确说明：当 provider 未设置时，OpenClaw 会按可用密钥自动探测 provider，常见顺序为：

1. Brave
2. Gemini
3. Kimi
4. Perplexity
5. Grok

示例

{
  tools: {
    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "${BRAVE_API_KEY}",
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        brave: {
          mode: "web",
        },
      },
    },
  },
}

6.2 tools.web.fetch

作用：控制 web_fetch 工具；其目标是抓取 URL 并提取正文内容。

版本提醒：tools.web.fetch 在不同 OpenClaw 版本中，官方文档、实现代码和严格 schema 之间可能存在轻微差异。若你配置后启动时报 unknown key，请以你本机版本的 schema 校验结果为准。

当前类型定义中已确认的核心参数

版本差异中常见的扩展参数

根据官方文档和仓库实现，某些版本还会出现以下扩展字段：

• tools.web.fetch.readability
• tools.web.fetch.maxResponseBytes
• tools.web.fetch.firecrawl.enabled
• tools.web.fetch.firecrawl.apiKey
• tools.web.fetch.firecrawl.baseUrl
• tools.web.fetch.firecrawl.onlyMainContent
• tools.web.fetch.firecrawl.maxAgeMs
• tools.web.fetch.firecrawl.timeoutSeconds

如果你的版本支持这些字段，它们的含义如下。

tools.web.fetch.firecrawl

如果网页直接抓取失败，或你需要更强的正文提取能力，可以配置 Firecrawl 作为回退。

常见参数：

• tools.web.fetch.firecrawl.enabled：是否启用 Firecrawl 回退
• tools.web.fetch.firecrawl.apiKey：Firecrawl API key，也可回退到 FIRECRAWL_API_KEY
• tools.web.fetch.firecrawl.baseUrl：Firecrawl API 地址，默认常见值为 https://api.firecrawl.dev
• tools.web.fetch.firecrawl.onlyMainContent：是否仅保留主内容
• tools.web.fetch.firecrawl.maxAgeMs：Firecrawl 缓存最大年龄
• tools.web.fetch.firecrawl.timeoutSeconds：Firecrawl 超时秒数

实际行为说明

• web_fetch 会优先做轻量抓取和正文提取
• 某些版本支持 readability 时，会优先尝试正文提取
• 某些版本配置了 Firecrawl 时，可在必要时走 Firecrawl 回退
• 对 JS 很重、反爬很强的网站，仍可能需要 browser 工具而不是 web_fetch

示例

{
  tools: {
    web: {
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        maxRedirects: 3,
        readability: true,
        firecrawl: {
          enabled: true,
          apiKey: "${FIRECRAWL_API_KEY}",
          baseUrl: "https://api.firecrawl.dev",
          onlyMainContent: true,
        },
      },
    },
  },
}

7. tools.media：媒体理解

tools.media 用于图像、音频、视频理解能力。

7.1 顶层结构

已确认结构：

• tools.media.models：共享模型列表
• tools.media.concurrency：并发数
• tools.media.image
• tools.media.audio
• tools.media.video

7.2 共享模型 tools.media.models[]

每个模型条目可配：

• provider：提供方 id
• model：模型 id
• capabilities：支持哪些能力，值可为 image / audio / video
• type：provider 或 cli
• command：CLI 模式下的命令
• args：CLI 参数模板
• prompt：提示词覆盖
• maxChars
• maxBytes
• timeoutSeconds
• language
• profile
• preferredProfile
• baseUrl
• headers
• providerOptions

7.3 单能力配置 tools.media.image/audio/video

每个能力块共通的常见参数：

• enabled
• scope
• maxBytes
• maxChars
• prompt
• timeoutSeconds
• language
• attachments
• models

其中 attachments 下包括：

• mode：first 或 all
• maxAttachments
• prefer：first / last / path / url

另外：

• audio.echoTranscript：是否把识别文本回显到聊天
• audio.echoFormat：回显格式模板

7.4 scope 的作用

可用于限制“在哪些消息上下文中启用媒体理解”。

已确认字段：

• scope.default
• scope.rules[]
• scope.rules[].match.channel
• scope.rules[].match.chatType
• scope.rules[].match.keyPrefix
• scope.rules[].action

8. tools.links：链接理解

用于对消息中的链接做额外处理。

已确认参数：

• tools.links.enabled
• tools.links.scope
• tools.links.maxLinks
• tools.links.timeoutSeconds
• tools.links.models[]

其中 models[] 支持：

• type：当前已确认可用 cli
• command
• args
• timeoutSeconds

9. tools.message：消息工具行为

主要控制跨上下文发送和广播。

9.1 已确认参数

• tools.message.allowCrossContextSend

  • 已标记为 deprecated
  • 建议改用 tools.message.crossContext.*

• tools.message.crossContext.allowWithinProvider

  • 是否允许同一 provider 内跨上下文发送

• tools.message.crossContext.allowAcrossProviders

  • 是否允许跨 provider 发送

• tools.message.crossContext.marker.enabled

  • 是否自动加来源标记

• tools.message.crossContext.marker.prefix

  • 前缀模板，支持 {channel}

• tools.message.crossContext.marker.suffix

  • 后缀模板，支持 {channel}

• tools.message.broadcast.enabled

  • 是否允许广播动作

9.2 示例

{
  tools: {
    message: {
      crossContext: {
        allowWithinProvider: true,
        allowAcrossProviders: false,
        marker: {
          enabled: true,
          prefix: "[from {channel}] ",
        },
      },
      broadcast: {
        enabled: true,
      },
    },
  },
}

10. tools.agentToAgent

用于一个 agent 在运行中调用另一个 agent。

已确认参数：

• tools.agentToAgent.enabled
• tools.agentToAgent.allow

作用说明：

• enabled：是否开放 agent-to-agent 工具面
• allow：允许访问哪些目标 agent id

建议：

• 默认关闭更安全
• 多 agent 编排场景再开启
• 一旦开启，最好显式写 allow

11. tools.sessions

控制 session 工具可见范围。

已确认参数：

• tools.sessions.visibility

允许值：

• self：仅当前会话
• tree：当前会话 + 当前会话生成的子会话（默认）
• agent：当前 agent 的所有会话
• all：所有会话

这个配置会影响：

• sessions_list
• sessions_history
• sessions_send

11.1 某些版本的 tools.sessions_spawn.attachments

在部分 OpenClaw 版本的 schema / 文档中，还可以看到 tools.sessions_spawn.attachments 相关配置，用于控制子会话派生时附件是否允许继承及附件大小限制。

常见字段包括：

• tools.sessions_spawn.attachments.enabled
• tools.sessions_spawn.attachments.maxTotalBytes
• tools.sessions_spawn.attachments.maxFiles
• tools.sessions_spawn.attachments.maxFileBytes
• tools.sessions_spawn.attachments.retainOnSessionKeep

如果你当前版本没有这些字段，请不要强行写入；仍应以实际 schema 校验结果为准。

12. tools.elevated

用于控制高权限执行路径。

已确认参数：

• tools.elevated.enabled
• tools.elevated.allowFrom

作用：

• enabled：是否启用 elevated 模式
• allowFrom：哪些发送者允许触发 elevated 工具

适合场景：

• 允许受信任操作者执行高风险命令
• 在共享群聊里保持关闭，只在私聊或管理员通道开放

13. tools.exec：命令执行工具

tools.exec 是 tools 中最需要谨慎配置的一组，因为它直接影响命令在哪里执行、是否需要审批、是否能写系统。

13.1 已确认参数总表

13.2 host 怎么选

• sandbox：优先推荐；在沙箱环境里执行，更安全
• gateway：直接在 Gateway 主机执行，风险最高但能力最强
• node：委派给连接节点执行，适合多节点/远端执行

13.3 security 怎么理解

• deny：最严格，默认更适合不信任输入
• allowlist：只允许明确白名单行为
• full：开放执行能力，风险最高

13.4 ask 怎么理解

• off：不要求确认
• on-miss：策略不明确时才确认
• always：每次都确认

实践建议：

• 私有开发环境可用 on-miss
• 面向多人共享或聊天入口时建议 always

13.5 safeBins 与 safeBinTrustedDirs

这是控制低风险二进制执行的关键配置。

• safeBins：允许“可视为安全”的命令
• safeBinTrustedDirs：额外声明哪些目录里的命令路径是可信的

适合用来放：

• 纯读取型工具
• 标准文本处理工具
• 你明确审计过的本地脚本

13.6 applyPatch 子工具

这是 exec 下非常特殊的子配置。

• tools.exec.applyPatch.enabled：是否启用 apply_patch
• tools.exec.applyPatch.workspaceOnly：是否只允许 patch workspace 内文件
• tools.exec.applyPatch.allowModels：限制只有某些模型能使用

建议：

• 生产或共享环境保持 workspaceOnly: true
• 只给可靠模型放开 allowModels

13.7 示例

{
  tools: {
    exec: {
      host: "sandbox",
      security: "allowlist",
      ask: "on-miss",
      safeBins: ["git", "npm", "node", "python"],
      backgroundMs: 2000,
      timeoutSec: 120,
      notifyOnExit: true,
      applyPatch: {
        enabled: true,
        workspaceOnly: true,
        allowModels: ["openai/gpt-5.2", "gpt-5.2"],
      },
    },
  },
}

14. tools.fs

用于控制文件系统类工具的路径边界。

已确认参数：

• tools.fs.workspaceOnly

作用：

• 为 read / write / edit / apply_patch 等文件工具限制访问范围
• true 时，只允许操作 agent workspace 内的文件

建议：

• 共享场景建议开启
• 私有开发环境可根据需要决定是否关闭

15. tools.loopDetection

用于检测工具调用循环，比如反复轮询、重复调用无进展、来回 ping-pong。

15.1 已确认参数

• tools.loopDetection.enabled
• tools.loopDetection.historySize
• tools.loopDetection.warningThreshold
• tools.loopDetection.criticalThreshold
• tools.loopDetection.globalCircuitBreakerThreshold
• tools.loopDetection.detectors.genericRepeat
• tools.loopDetection.detectors.knownPollNoProgress
• tools.loopDetection.detectors.pingPong

15.2 参数作用

• historySize：保留多少条调用历史用于检测
• warningThreshold：达到多少次开始警告
• criticalThreshold：达到多少次视为严重循环
• globalCircuitBreakerThreshold：全局断路阈值
• genericRepeat：识别相同调用重复
• knownPollNoProgress：识别无进展轮询
• pingPong：识别你一下我一下的来回循环

建议：

• 自主运行/自动化任务较多时建议开启
• 子 agent 大量串行调用时尤其有用

16. tools.subagents

用于定义“派生出来的子 agent”默认使用什么模型、有什么工具权限。

16.1 已确认参数

• tools.subagents.model
• tools.subagents.tools.allow
• tools.subagents.tools.alsoAllow
• tools.subagents.tools.deny

其中 model 支持两种写法：

• 字符串：直接指定主模型
• 对象：{ primary, fallbacks }

16.2 适用场景

• 主 agent 很强，但你希望子 agent 更受限
• 主 agent 可写文件，但子 agent 只能读
• 子 agent 专门做搜索、分析、归纳，不允许 exec

示例：

{
  tools: {
    subagents: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-4.1"],
      },
      tools: {
        allow: ["read", "web_search", "web_fetch", "sessions_history"],
        deny: ["write", "edit", "apply_patch", "exec"],
      },
    },
  },
}

17. tools.sandbox

这是“在沙箱上下文中允不允许哪些工具”的默认策略层。

已确认参数：

• tools.sandbox.tools.allow
• tools.sandbox.tools.deny

作用：

• 当 agent 在 sandbox 执行环境下运行时，可额外应用一层工具 allow/deny
• 适合做比主环境更严格的能力收缩

18. 每 agent 的 tools 覆盖

除了全局 tools，OpenClaw 还支持 agents.list[].tools 做单 agent 覆盖。

已确认可用子参数：

• agents.list[].tools.profile
• agents.list[].tools.allow
• agents.list[].tools.alsoAllow
• agents.list[].tools.deny
• agents.list[].tools.byProvider
• agents.list[].tools.elevated
• agents.list[].tools.exec
• agents.list[].tools.fs
• agents.list[].tools.loopDetection
• agents.list[].tools.sandbox.tools

这意味着你可以做出类似这种分层：

• 全局允许 read / web_fetch
• agent-a 额外允许 exec
• agent-b 明确禁止 write

19. tools 常见误配与建议

19.1 把 web 和 tools.web 混了

• web：渠道运行时配置
• tools.web：搜索/抓取工具配置

19.2 只写 allow，忘了 deny 的兜底

建议：

• 有高风险工具时，显式在 deny 中写出来更稳

19.3 开了 exec.host = "gateway" 却没收紧权限

后果：

• 命令可能直接在网关主机执行
• 如果再配合 security = "full"，风险很高

19.4 给子 agent 的权限和主 agent 一样大

建议：

• 子 agent 默认更适合“只读、少写、少 exec”

19.5 开了 web_fetch 却期待它处理所有复杂网页

说明：

• 静态网页正文提取适合 web_fetch
• 登录态、重 JS、反爬页面仍然更适合 browser

20. 一个更实用的参考示例

下面给一个“通用开发型”配置片段，只展示关键部分：

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
    list: [
      {
        id: "main",
        identity: {
          name: "OpenClaw",
          emoji: "🦞",
        },
      },
    ],
  },

  tools: {
    profile: "coding",
    alsoAllow: ["web_fetch", "web_search"],
    deny: ["browser"],

    web: {
      search: {
        enabled: true,
        provider: "brave",
        apiKey: "${BRAVE_API_KEY}",
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 30000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        readability: true,
      },
    },

    exec: {
      host: "sandbox",
      security: "allowlist",
      ask: "on-miss",
      safeBins: ["git", "node", "npm", "python"],
      timeoutSec: 120,
      applyPatch: {
        enabled: true,
        workspaceOnly: true,
      },
    },

    fs: {
      workspaceOnly: true,
    },

    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
    },

    subagents: {
      tools: {
        allow: ["read", "web_search", "web_fetch", "sessions_history"],
        deny: ["write", "edit", "apply_patch", "exec"],
      },
    },
  },

  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
    },
  },
}

21. 配置整理建议

如果你要自己维护一份长期可用的 openclaw.json，建议按下面的顺序配置：

1. 先配 agents.defaults.workspace
2. 再配 channels.*，确保只有你允许的人能触发
3. 再配 models.* 和 API key
4. 再配 tools.profile、allow、deny
5. 最后再开 exec、elevated、agentToAgent 这类高风险能力

对于生产或共享聊天入口，优先考虑：

• tools.fs.workspaceOnly = true
• tools.exec.host = "sandbox"
• tools.exec.security = "allowlist"
• tools.elevated.enabled = false 或严格限制 allowFrom
• tools.subagents.tools.deny 中显式禁止写入与执行类工具

22. 当前版本的“现行 / 已废弃”说明

根据当前已读取的类型定义，以下字段已经明确带有“过时/迁移中”标记：

• tools.message.allowCrossContextSend：已建议迁移到 tools.message.crossContext.*
• tools.web.search.perplexity.baseUrl：legacy / deprecated，对 Search API 忽略
• tools.web.search.perplexity.model：legacy / deprecated，对 Search API 忽略
• tools.media.* 中的 deepgram 旧参数结构：已建议迁移到 providerOptions.deepgram

除此之外，本次读取到的顶层结构中没有看到更多被明确标为弃用的 tools 主路径字段。后续升级时，建议继续以 OpenClaw 的类型定义和官方配置文档为准。

23. 参考来源

本说明整理时使用了以下来源：

• 官方文档：https://openclawlab.com/en/docs/gateway/configuration/
• 官方文档：https://openclawlab.com/en/docs/reference/config/
• 官方 CLI 文档：https://openclawlab.com/en/docs/cli/config/
• 官方工具文档：https://openclawlab.com/en/docs/tools/web/
• 官方仓库：openclaw/openclaw
• 源码类型：src/config/types.openclaw.ts
• 源码类型：src/config/types.tools.ts
• 源码说明：src/config/schema.help.ts

如果你后面希望，我还可以继续基于这一份文档再帮你做两种扩展版本：

1. 生成一份“按实际使用场景分类”的精简版（开发型 / 公网型 / 多 agent 型）
2. 直接给你补一份带注释的 openclaw.json 示例模板