configure-OpenClaw

概述

通过最小化、经过验证的补丁安全地修改 ~/.openclaw/openclaw.json。OpenClaw 使用严格的模式验证——未知字段或格式错误的值会阻止启动。每次编辑在写入前都必须正确无误。

安全编辑流程

dot
digraph config_edit {
读取当前配置 [shape=box];
分析用户意图 [shape=box];
需要了解不熟悉字段的详细信息？ [shape=diamond];
获取实时文档 (WebFetch) [shape=box];
提议：解释 + 最小化补丁 [shape=box];
用户确认？ [shape=diamond];
应用：深度合并 + 写入 [shape=box];
中止 [shape=box];

读取当前配置 -> 分析用户意图;
分析用户意图 -> 需要了解不熟悉字段的详细信息？;
需要了解不熟悉字段的详细信息？ -> 获取实时文档 (WebFetch) [label=是];
需要了解不熟悉字段的详细信息？ -> 提议：解释 + 最小化补丁 [label=否];
获取实时文档 (WebFetch) -> 提议：解释 + 最小化补丁;
提议：解释 + 最小化补丁 -> 用户确认？;
用户确认？ -> 应用：深度合并 + 写入 [label=是];
用户确认？ -> 中止 [label=否];
}

硬性规则——无例外：

• - 未经用户确认绝不写入文件
• 除非用户明确要求，绝不输出完整配置
• 仅修改用户请求的字段——不做额外编辑
• 绝不猜测未知字段——先获取实时文档
• 大多数部分的配置更改支持热重载——无需重启
• 仅以下情况需要重启：网关服务器设置（端口、绑定、认证、TLS）、基础设施（发现、插件）
• 如果编辑后启动失败，运行 openclaw doctor 进行诊断，openclaw doctor --fix 自动修复

输出格式

自然语言解释 + 最小化 JSON5 补丁（仅包含更改的字段）：

将 agents.defaults.model.primary 从 anthropic/claude-sonnet-4-6 更改为 anthropic/claude-opus-4-6。

// 补丁
{
agents: {
defaults: {
model: {
primary: anthropic/claude-opus-4-6,
},
},
},
}

实时文档——需要时获取

当请求的字段不在下面的快速参考中，或需要验证允许的值时：

• - 配置概述： https://docs.openclaw.ai/gateway/configuration
• 字段参考： https://docs.openclaw.ai/gateway/configuration-reference
• 示例： https://docs.openclaw.ai/gateway/configuration-examples

CLI 替代方案

• - openclaw onboard — 完整交互式设置
• openclaw configure — 配置向导
• openclaw config get/set/unset — CLI 字段访问
• 控制界面位于 http://127.0.0.1:18789 的配置选项卡

快速参考

格式规则

identity

json5
{
identity: {
name: Clawd, // 机器人显示名称
theme: helpful assistant,
emoji: 🦞,
}
}

agents.defaults

json5
{
agents: {
defaults: {
workspace: ~/.openclaw/workspace, // 必需
model: {
primary: anthropic/claude-sonnet-4-6,
fallbacks: [anthropic/claude-opus-4-6],
},
imageModel: { primary: anthropic/claude-sonnet-4-6 },
imageGenerationModel: { primary: anthropic/claude-sonnet-4-6 },
pdfModel: { primary: anthropic/claude-sonnet-4-6 },
pdfMaxBytesMb: 10,
pdfMaxPages: 20,
imageMaxDimensionPx: 1200,
timeoutSeconds: 600,
maxConcurrent: 3,
contextTokens: 200000,
mediaMaxMb: 5,
userTimezone: America/New_York, // IANA 时区
timeFormat: auto, // auto | 12 | 24
thinkingDefault: low, // off | minimal | low | medium | high | xhigh | adaptive
elevatedDefault: on, // off | on | ask | full
verboseDefault: off, // off | on | full
typingMode: instant, // never | instant | thinking | message
typingIntervalSeconds: 6,
sandbox: {
mode: off, // off | non-main | all
backend: docker, // docker | ssh | openshell
scope: session, // session | agent | shared
workspaceAccess: none, // none | ro | rw
},
heartbeat: {
every: 30m, // 持续时间字符串；0m 禁用
target: none, // none | last | 频道名称
directPolicy: allow, // allow | block
isolatedSession: false,
prompt: , // 自定义心跳提示
},
compaction: {
mode: safeguard, // default | safeguard
timeoutSeconds: 900,
reserveTokensFloor: 24000,
identifierPolicy: strict, // strict | off | custom
memoryFlush: { enabled: true, softThresholdTokens: 6000 },
},
contextPruning: {
mode: cache-ttl, // off | cache-ttl
ttl: 1h,
keepLastAssistants: 3,
},
subagents: {
maxConcurrent: 8,
runTimeoutSeconds: 900,
archiveAfterMinutes: 60,
},
blockStreamingDefault: off, // on | off
},
list: [ // 多代理设置
{
id: default,
default: true,
workspace: ~/.openclaw/workspace,
identity: { name: Bot, theme: assistant, emoji: 🤖 },
groupChat: { mentionPatterns: [@bot] },
},
],
}
}

channels

支持的平台：WhatsApp、Telegram、Discord、Slack、Signal、iMessage、Google Chat、Mattermost、MS Teams、Matrix、IRC、BlueBubbles。

json5
{
channels: {
whatsapp: {
allowFrom: [+15555550123],
dmPolicy: pairing, // pairing | allowlist | open | disabled
groupPolicy: allowlist, // pairing | allowlist | open | disabled
groups: { *: { requireMention: true } },
textChunkLimit: 4000,
chunkMode: length, // length | newline
mediaMaxMb: 50,
sendReadReceipts: true