Configurations

关键配置不是字段大全，而是系统边界

这页的重点不是把所有配置项一次性背下来，而是先建立判断顺序：哪些配置决定入口边界，哪些决定默认行为，哪些适合在系统稳定后再加上去。

主配置文件~/.openclaw/openclaw.json

默认主配置文件使用 JSON5。最稳妥的做法是先跑通一条最小链路，再逐层加复杂度。

推荐入口onboard / configure / config

首次配置优先用向导或 CLI helper，避免一开始直接在大文件里手改所有字段。

真正高风险Gateway、认证、渠道白名单

凡是改变访问边界、执行权限和远程入口的配置，都应该先按生产能力来管理。

Edit Paths

4 种更稳的改配置方式

先选对入口，能减少很多无效排查。第一次配置、日常调整、脚本化维护和直接编辑，不该混成同一种操作习惯。

首次安装或重整配置

openclaw onboard

适合第一次把模型、Gateway、UI 和基础能力串起来。先用它建立可运行基线。

交互式调整配置

openclaw configure

适合模型、渠道、Skills 和 Gateway 的增量调整，比手写整段 JSON5 更稳。

非交互式修改或排查

openclaw config get|set|unset|validate

适合脚本化、远程维护和精确定位单个配置项，不需要整个向导流程。

Control UI 或直接编辑

Control UI / 编辑 openclaw.json

更适合确认结果或做少量改动。大范围改动前先确保你已经理解字段边界。

Layers

先按配置分层理解

把配置看成六层结构，比直接从一大份 JSON5 文件里找问题更稳，也更适合长期维护。

入口边界

Gateway 与认证

决定服务如何暴露、走什么认证、Control UI 用什么安全上下文，以及远程访问是否经过受控通道。

host / bindauth.modecontrolUitrustedProxies

全局默认

agents.defaults

决定默认模型、workspace、工具行为和系统级运行基线。大多数“为什么表现不对”都先回到这里看。

model.primaryfallbacksworkspacebootstrap limits

模型边界

模型目录与 allowlist

决定默认模型、备用链和 `/model` 可选范围。只有真正允许的模型才应该暴露给会话切换。

agents.modelsagents.defaults.modelsprovider auth

消息入口

channels

决定哪些渠道接入、私信怎么处理、群里何时响应、哪些用户或聊天可以触发系统。

dmPolicyallowFromgroups.*.requireMentionaccountId

上下文隔离

session

决定私信按什么粒度合并、线程怎么绑定、什么时候自动重置。这个层直接影响“记忆串不串台”。

dmScopeidentityLinksthreadBindingsreset

能力加载

skills 与工具扩展

决定内置技能是否启用、额外目录从哪里加载、是否监听本地变化，以及单项技能是否启停。

allowBundledload.extraDirsload.watchentries.enabled

Presets

从 4 种典型场景开始，比空白起步更稳

先跑通最小链路

适合第一次搭好模型、workspace 和单一入口，不要一开始同时上多渠道和多模型。

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: { primary: "anthropic/claude-sonnet-4-6" }
    }
  },
  gateway: {
    host: "127.0.0.1"
  }
}

多模型但仍可控

主力模型负责稳定任务，备用模型负责限速和不可用场景，allowlist 决定会话里能切哪些模型。

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.4"]
      },
      models: [
        "anthropic/claude-sonnet-4-6",
        "openai/gpt-5.4"
      ]
    }
  }
}

多渠道但先收入口

接入渠道后，优先配置 allowFrom、dmPolicy 和群组 mention 规则，避免机器人变成公开入口。

{
  channels: {
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["tg:123456"],
      groups: {
        "*": { requireMention: true }
      }
    }
  }
}

本地 Skills 开发

用额外目录和 watch 支持本地迭代，同时明确哪些 bundled skills 真正允许加载。

{
  skills: {
    allowBundled: ["peekaboo"],
    load: {
      extraDirs: ["~/Projects/openclaw-skills"],
      watch: true
    },
    entries: {
      peekaboo: { enabled: true }
    }
  }
}

Risk

最常见的 6 个配置误区

把 Gateway 直接绑到公网地址

如果只是想远程访问，优先 SSH tunnel 或 Tailscale Serve。先开公网再补认证，顺序反了。

Control UI 长期开启不安全模式

`gateway.controlUi.allowInsecureAuth` 和 `dangerouslyDisableDeviceAuth` 都只适合临时救火，不是日常配置。

trustedProxies 写得过宽

只有你完全控制的代理 IP 才应该被信任。否则转发头会把边界一起放宽。

渠道接入后不做 allowFrom

没有白名单和 mention 规则，消息入口很容易从受控机器人变成谁都能触发的执行入口。

一开始就堆多 Agent 与复杂绑定

在默认模型、session 和单一渠道都还没稳定前，多 agent 和 bindings 会放大排查成本。

把 SOUL 当成万能配置

SOUL 决定行为风格和边界，但不能替代模型、权限、审批、白名单和 Gateway 安全配置。

Commands

先把这些命令跑顺

CLI helper

# 查看当前配置文件路径
openclaw config file

# 查看某个配置值
openclaw config get gateway.auth.mode

# 设置某个配置值
openclaw config set gateway.host "127.0.0.1"

# 移除某个配置值
openclaw config unset channels.telegram.allowFrom

# 校验当前配置
openclaw config validate

更稳的配置顺序

1. 先跑 onboard / configure，建立可运行基线
2. 再确认 gateway / auth / channels 边界
3. 然后确定默认模型与 fallback
4. 最后再加 session、skills、hooks 和多 agent

FAQ

配置页里最值得先澄清的问题

配置文件默认放在哪里？

默认主配置文件是 `~/.openclaw/openclaw.json`。敏感信息更适合放到环境变量或专门的 secret 引用里，而不是直接硬编码。

优先用向导还是直接改文件？

首次配置优先 `openclaw onboard` 或 `openclaw configure`。只有在你已经知道目标字段时，才建议直接编辑或用 `openclaw config set`。

怎么验证配置是否真的生效？

先用 `openclaw config validate` 看结构是否通过，再通过 Control UI、日志或实际渠道行为确认运行时结果。

修改配置后都需要重启吗？

不一定。是否热应用取决于具体配置项和 reload 行为，但涉及 Gateway、认证或高风险入口变化时，应该按需要重启来处理。

SOUL 应该放在这页的什么位置理解？

SOUL 是行为层配置，不是整套关键配置的中心。更稳的顺序是先把模型、入口、权限和会话跑稳，再调 SOUL。

多 agent 和 bindings 什么时候再上？

至少在单 agent、默认模型、session.dmScope 和单一渠道都稳定后再做。否则你很难判断问题来自配置结构还是业务逻辑。

Cross Links

继续把配置问题放回对应主题里

这页负责判断顺序。到了具体模型、Skills、安全边界和安装路径时，继续回到对应主题页会更准确。