OpenClaw 2026.10.6 配置参数详解

目标：系统讲清 OpenClaw（v2026.10.6）的配置体系——配置文件位置与格式、四种查看/修改途径、严格校验与热重载行为、47 个顶层配置节的参数总览与核心参数逐项详解，并给出可直接落地的生产配置模板。文中命令与回显均在 Ubuntu 24.04 + OpenClaw 2026.10.6（构建号 fe06181）环境实测。

一、环境信息

• 操作系统：Ubuntu 24.04.5 LTS（x86_64）
• OpenClaw 版本：2026.10.6（fe06181）；Node.js 24.22.1；npm 11.19.1
• 配置文件：~/.openclaw/openclaw.json（JSON5 格式，可选文件——缺失时使用安全默认值）
• 状态目录：~/.openclaw/（SQLite 状态库、会话库、工作区）
• Gateway：监听 ws://127.0.0.1:18789，Control UI http://127.0.0.1:18789/
• 实测时间：2026-10-23

二、前置条件

已完成安装并写入最小配置（安装步骤见 《OpenClaw Ubuntu 24.04 安装指南》第四章/第八章），至少能执行 openclaw config file 拿到配置路径：

openclaw config file

实测输出：

/root/.openclaw/openclaw.json

💡 说明：OpenClaw 读取的是可选的 JSON5 配置文件 ~/.openclaw/openclaw.json，文件不存在时全部走安全默认值。因此"改配置"的前提是知道当前生效路径——用 openclaw config file 确认，而不是猜路径。若需把配置放在默认状态目录之外，用环境变量 OPENCLAW_CONFIG_PATH 直接指向真实文件。

三、参数查看与修改方式

3.1 四种修改途径

OpenClaw 官方支持四种配置修改方式，按场景选用（来源：官方文档《Gateway/Configuration》，结合实测）：

💡 技术拓展：config set 支持三种取值模式——value 模式（直接给值）、ref 模式（--ref-provider default --ref-source env --ref-id XXX，把值指向环境变量/文件等外部来源而不落明文）、batch JSON 模式（--batch-json '[{"path":"gateway.mode","value":"local"}]' 一次写多条）。本文示例以 value 模式为主，敏感凭据建议用 ref 模式。

3.2 CLI 读写实测

读单条参数（点路径寻址）：

openclaw config get gateway.mode
openclaw config get agents.defaults.workspace

实测输出：

local

/root/.openclaw/workspace

写单条参数（改后 Gateway 热重载或提示重启）：

openclaw config set gateway.mode local
openclaw config set agents.defaults.userTimezone "Asia/Shanghai"

实测输出：

Updated gateway.mode. Restart the gateway to apply.

Updated agents.defaults.userTimezone. Change will apply without restarting the gateway.

💡 说明：输出直接告诉你生效方式——gateway.* 基础设施项需重启 Gateway，agents.* 等 Agent 环节参数热生效免重启。

3.3 热重载行为（实测）

Gateway 常驻进程会监视配置文件，保存即评估重载。实测把时区改为 Asia/Shanghai 后，服务日志（journalctl --user -u openclaw-gateway）出现：

[reload] config change detected; evaluating reload (agents.defaults.userTimezone)
[reload] config hot reload applied (agents.defaults.userTimezone)
[reload] config source revision 1 accepted (file)

三行日志对应"检测变更 → 评估 → 热应用"全链路，无需重启。

3.4 严格校验与非法配置的实测表现

OpenClaw 只接受完全匹配 schema 的配置：未知键、错误类型、非法值都会被拒绝。唯一例外是根级 $schema 字符串键（供编辑器挂 JSON Schema 用）。

热重载阶段的拒绝（实测）：向 gateway 节手工塞一个未知键 unknownKeyTest 后，日志显示热重载被跳过且运行时保持上一个已接受配置：

[reload] config reload skipped (invalid config): gateway: Unrecognized key: "unknownKeyTest"

把文件还原后：

openclaw config validate

实测输出：

Config valid: ~/.openclaw/openclaw.json

启动阶段的拒绝：配置非法时 Gateway 拒绝启动，仅诊断类命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）。修复命令：

openclaw doctor --fix --non-interactive

配套机制（官方文档，实测可见其效果）：Gateway 每次成功启动都会留存 last-known-good 配置副本，被误清空的配置（文件体积骤降一半以上、丢失 gateway.mode 等）会触发写保护，被拒写入会另存为 <路径>.rejected.<时间戳> 供检查；启动迁移沿用与 doctor --fix 相同的固定变换，迁移前的配置进入 .bak 轮换。

3.5 拆分文件与环境变量引用

• $include 拆分：主配置可用 $include 把分节拆到多个文件（适合把渠道凭据单独成文件管理）；使用 $include、Nix 管理或由更新版本 OpenClaw 写出的配置不会被自动迁移，需手工处理。
• 环境变量注入：配置值支持 ${VAR} 替换（运行时从环境读取）；Gateway 服务单元会注入 OPENCLAW_GATEWAY_PORT 等变量（见安装指南 8.3 节单元文件实测）。
• SecretRef 密钥引用：凭据类值支持 env/file/exec/store 四类来源引用，避免明文落盘；openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN 即把 Discord 令牌指向环境变量。

四、参数总览

openclaw config schema 输出当前版本权威 JSON Schema（Control UI 表单与校验都用它）。实测 2026.10.6 共 47 个顶层配置节：

openclaw config schema 2>/dev/null | python3 -c "import json,sys; print(list(json.load(sys.stdin)['properties'].keys()))"

实测输出（节选首行）：

['$schema', 'meta', 'env', 'wizard', 'diagnostics', 'logging', 'update', 'telemetry', 'browser', 'ui', 'secrets', 'auth', 'accessGroups', 'acp', 'models', 'nodeHost', 'agents', 'worktreeRoot', 'worktreeAcceleration', 'worktreeMaxCount', 'tools', 'security', 'bindings', 'broadcast', 'attachments', 'messages', 'tts', 'commands', 'approvals', 'session', 'cron', 'transcripts', 'hooks', 'channels', 'discovery', 'talk', 'gateway', 'cloudWorkers', 'storage', 'desktop', 'memory', 'mcp', 'skills', 'plugins', 'surfaces', 'proxy']

按用途分组解读：

关键差异解读：OpenClaw 采用"两桶"结构——根级兄弟键（如 gateway、channels、tools）承载基础设施与跨 Agent 默认，agents.defaults 承载 Agent 循环行为，agents.entries.<名称> 可对单个 Agent 覆盖两桶中 schema 允许的任意项。改参数前先判断它属于哪一桶，放错层级会被校验拒绝。

五、核心参数分类详解

5.1 gateway.*：网关基础设施

gateway 节实测子键：port, mode, bind, customBindHost, publicOrigin, portals, github, projects, controlUi, uploads, cliAgents, terminal, auth, roles。

⚠️ 注意：gateway.bind=lan 或配置 publicOrigin 前先评估暴露面——Gateway 是能执行命令的强能力控制面，官方 exposure runbook 要求配齐鉴权、反向代理与防火墙再对外。

5.2 agents.*：Agent 工作区与模型

agents 节实测子键：ownership, defaults, entries。agents.defaults 实测子键（前 18 个）：params, model, modelSelectionScope, utilityModel, decisionModel, imageModel, mediaModels, voiceModel, pdfModel, pdfMaxMb, pdfMaxPages, models, modelPolicy, workspace, cwd, skills, silentReply, repoRoot。

5.3 session.*：会话作用域与重置

session 节实测子键：scope, dmScope, groupScope, notifyOnCreate, identityLinks, resetTriggers, reset, resetByType, resetByChannel, store, mainKey, sendPolicy, threadBindings, sharing。

• session.dmScope / session.groupScope：私聊/群聊的会话隔离粒度（按渠道、按对端、按线程等维度组合，决定"谁和谁共享一个会话上下文"）。
• session.resetTriggers / session.reset / resetByType / resetByChannel：会话重置触发词与按消息类型/渠道的重置策略。
• session.store：会话存储位置；实测主会话库落在 ~/.openclaw/agents/main/agent/openclaw-agent.sqlite（openclaw health 回显可见）。
• session.sendPolicy：出站消息发送策略（限速、窗口）。

5.4 commands.*：聊天命令与所有者

commands 节实测子键：native, nativeSkills, text, bash, bashForegroundMs, config, mcp, plugins, debug, restart, ownerAllowFrom, allowFrom。

• commands.ownerAllowFrom：命令所有者白名单（数组，渠道原生 ID，可加渠道前缀如 "telegram:123456789"）。所有者才被允许执行 /update、重启 Gateway、改配置、审批命令等高权操作——实测 openclaw status 会提示 Heartbeat ... waiting for delivery route — set commands.ownerAllowFrom=[...]。
• commands.debug：设 true 才允许聊天里的 /debug 运行时覆盖命令。
• commands.bash / bashForegroundMs：聊天内 bash 命令的开关与前台超时。

5.5 channels.*：渠道接入

channels 节实测子键（前 14 个）：defaults, modelByChannel, a2a, buzz, clickclack, discord, feishu, googlechat, imessage, irc, line, matrix, mattermost, msteams（其余含 signal, slack, sms, telegram, whatsapp, wechat, wecom, qq, zalo, nostr, twitch, synology, nextcloud, x 等，覆盖 20+ 渠道）。

通用形态（以官方最小配置示例与实测配置为准）：

• 每个渠道一个同名子节，凭据字段（如 token）建议用 SecretRef 指向环境变量；
• 访问控制类字段控制"谁能跟机器人说话"：DM 白名单、群组门控（群聊需 @ 提及才触发）等；
• channels.defaults 提供跨渠道缺省；modelByChannel 可按渠道覆盖模型。

最小渠道示例（官方文档原样形态，allowFrom 限定了允许的发送者）：

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

5.6 models.*：模型供应商

models 节实测子键：mode, providers, catalogRefresh。

• models.providers：自定义/本地 provider 声明（OpenAI 兼容端点、Ollama、vLLM、LM Studio 等），支持 baseUrl + apiKey 引用；
• models.catalogRefresh：官方模型目录刷新策略（Gateway 启动日志可见 remote model catalog applied）；
• 模型故障转移与优先级在 agents.defaults.modelPolicy / models 配合下生效。

5.7 tools.*：工具策略

tools 节实测子键：profile, allow, alsoAllow, deny, byProvider, toolsBySender, web, github, media, links, sessions, loopDetection, toolSearch, codeMode。

• tools.profile：工具暴露档位（整体收紧/放宽的预设）；
• tools.allow / alsoAllow / deny：白名单、追加白名单、黑名单三级控制；
• toolsBySender：按发送者差异化工具权限（访客降权）；
• tools.web：网页抓取/搜索类工具配置；tools.loopDetection：工具循环检测。

5.8 browser.*：托管浏览器

browser 节实测子键：enabled, allowSystemProfileImport, evaluateEnabled, cdpUrl, executablePath, headless, noSandbox, attachOnly, defaultProfile, snapshotDefaults, ssrfPolicy, profiles, extraArgs, tabCleanup。

• browser.enabled：启用 Gateway 托管浏览器（Docker -browser 变体镜像内置 Chromium 时配合使用）；
• browser.executablePath：显式指定浏览器可执行文件（容器部署时必须指向容器内路径）；
• browser.headless：无头模式（服务器/NAS 无显示器环境设 true）；
• browser.ssrfPolicy：防 SSRF 策略；browser.profiles：多 profile 管理。

5.9 memory.* 与 security.*

• memory 节实测子键：citations, search——记忆检索开关与引用标注；实测 openclaw memory status 显示默认检索 provider 为 openai（模型 text-embedding-3-small），索引来源 memory, sessions。
• security 节实测子键：audit, installPolicy——安全审计与插件安装策略；openclaw security audit 命令按此执行检查。

5.10 环境变量速查

六、生产配置模板

个人助理 + Telegram 渠道的生产起点模板（2 GB 内存服务器、本地自用、凭据走环境变量引用）。字段名均来自 5.x 节 schema 实测，凭据值请按自己的账号生成：

{
  // 基础设施：本机模式 + 回环绑定 + 随机令牌（用 doctor --fix --generate-gateway-token 生成后回填）
  gateway: {
    mode: "local",
    bind: "loopback",
    auth: {
      mode: "token",
      token: "oc_prod_2026_q1w2e3r4"
    }
  },
  // Agent 默认：工作区与时区；模型先用官方目录默认，按需加 agents.defaults.model
  agents: {
    defaults: {
      workspace: "/root/.openclaw/workspace",
      userTimezone: "Asia/Shanghai"
    }
  },
  // 命令所有者：只有白名单内的渠道账号能执行高权命令
  commands: {
    ownerAllowFrom: ["telegram:123456789"]
  },
  // 渠道：凭据用 SecretRef 指向环境变量，不落明文
  channels: {
    telegram: {
      token: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["123456789"]
    }
  },
  // 浏览器：服务器无显示器，强制无头
  browser: {
    enabled: true,
    headless: true
  }
}

逐项说明：bind=loopback 保持控制面仅本机可达（远程使用建议走 Tailscale/反代 + publicOrigin，而不是直接改 lan）；ownerAllowFrom 必须配，否则心跳/审批等管理动作没有投递目标（实测 status 提示项）；allowFrom 与 ownerAllowFrom 是两道独立闸门——前者管"谁能聊"，后者管"谁能管"。模板落盘后先执行 openclaw config validate 确认合法（实测回显 Config valid: ...）；config set 未覆盖到的字段，直接编辑配置文件走热重载即可。

⚠️ 注意：模板中 token 示例值仅作演示，生产令牌务必用 openclaw doctor --fix --generate-gateway-token 生成的高熵随机值；渠道白名单 ID 用你自己账号的真实 ID（获取方式见各渠道接入文档）。

七、常见问题（FAQ）

Q1：改了 gateway.* 参数为什么没生效？ 基础设施参数不走热重载，config set 会明确提示 Restart the gateway to apply（实测回显见 3.2 节）。执行 systemctl --user restart openclaw-gateway（或重启 Docker 容器）后生效。

Q2：Gateway 因配置非法拒绝启动，怎么办？ 只保留诊断命令可用是预期行为。依次执行 openclaw doctor（看具体问题）→ openclaw doctor --fix --non-interactive（自动修复旧键/迁移）。若手头有 last-known-good 副本，也可对比 .bak 轮换文件定位差异。

Q3：配置里能写注释吗？ 能。配置文件是 JSON5 格式，支持 // 行注释与尾逗号（官方示例即带注释，见 5.5 节）。但通过 config set 写入的内容会规范化，注释可能被整理掉。

Q4：怎么查某个参数的确切类型与默认值？ 用 openclaw config schema 拿全量 JSON Schema（含每个字段的 title/description 元数据与默认值）；Control UI 的 Config 表单也按同一 schema 渲染，高级字段收在「Advanced (N)」折叠组里。

Q5：多套配置如何在同一台机器隔离？ 用命名 profile：openclaw --profile work <命令> 会把状态与配置隔离到 ~/.openclaw-work/；开发调试用 --dev（隔离到 ~/.openclaw-dev，端口改 19001）。两个机制底层分别是 OPENCLAW_STATE_DIR 与 OPENCLAW_CONFIG_PATH 环境变量（CLI 帮助实测）。

八、参考链接

• 官方配置总览：https://docs.openclaw.ai/gateway/configuration
• 配置参考（全字段）：https://docs.openclaw.ai/gateway/configuration-reference
• 环境变量文档：https://docs.openclaw.ai/gateway/configuration/environment
• Doctor 修复：https://docs.openclaw.ai/doctor
• CLI 参考：https://docs.openclaw.ai/cli
• 本站认知篇：《OpenClaw 介绍与选型指南》
• 本站部署篇：《OpenClaw Ubuntu 24.04 安装指南》