配置模板与样例

本附录提供与官方配置结构对齐的 JSON5 示例，用于快速搭建最小可用系统，并给出可逐步演进到生产的配置组织方式。字段细节可能随版本演进，建议在变更后用 doctor、status 做一次验证。

B.1 配置文件位置与格式

OpenClaw Gateway 的主配置文件默认路径为 ~/.openclaw/openclaw.json，格式为 JSON5。JSON5 支持注释与尾逗号，适合工程维护，但也更容易因拼写或层级错误导致配置不生效。

建议把配置治理拆成两层。

• 结构层：渠道策略、会话与记忆、工具治理、诊断配置等稳定结构。

• 机密层：模型供应商密钥、渠道令牌等敏感字段，通过环境变量或密钥系统注入。

B.2 最小可用配置（本地模式 + Web 验证）

该示例用于本地起步：打开本地模式，启用诊断落盘，并保留默认智能体工作区。启动后用 health/status 验证，再用 Dashboard 进入 WebChat 做最小交互。

[!WARNING] OpenClaw 对配置会有严格的 Schema 校验。配置未知键会导致 Gateway 拒绝启动。

{
  gateway: {
    mode: "local",
  },

  logging: {
    file: "/tmp/openclaw/openclaw-%DATE%.log",
    level: "info",
    consoleLevel: "info",
    consoleStyle: "pretty",
    // 注意：redaction 主要作用于控制台/TTY 输出（不要承诺“文件日志完全脱敏”）
    redactSensitive: "tools",
  },

  diagnostics: {
    enabled: true,
    dumpOnCrash: true,
  },

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

操作验证命令：

openclaw health --json
openclaw status --deep
openclaw dashboard

B.3 WhatsApp 安全起步模板（配对 + 白名单 + 群聊门控）

该示例把触发面收敛到可控范围。

• 私聊：默认配对，陌生私聊必须审批。

• 白名单：只允许明确号码触发。

• 群聊：默认要求提及，并建议配合群组允许列表。

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["[phone]"],

      groupPolicy: "allowlist",
      groupAllowFrom: ["[phone]"],

      groups: { "*": { requireMention: true } },
    },
  },

  messages: {
    groupChat: {
      mentionPatterns: ["@openclaw"],
    },
  },
}

渠道登录与配对审批参考：

• WhatsApp 渠道：https://docs.openclaw.ai/channels/whatsapp

• pairing 命令：https://docs.openclaw.ai/cli/pairing

B.4 Telegram 最小模板（单账号）

Telegram 以机器人 token 为核心，适合快速验证。该示例展示最小结构与建议的访问控制。

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",

      dmPolicy: "allowlist",
      allowFrom: ["tg:123456789"],

      groupPolicy: "disabled",
    },
  },
}

Telegram 渠道参考：https://docs.openclaw.ai/channels/telegram。

B.5 工具治理模板

工具治理的官方配置以 tools.profile 作为基础模板，并包含 tools.allow 与 tools.deny。默认策略是允许该 profile 下的全部工具；显式 deny 会覆盖 allow；channels.*.groups.*.tools 用于按渠道与群组分层治理。参考：https://docs.openclaw.ai/tools 与 https://docs.openclaw.ai/channels/groups#groupchannel-tool-restrictions-optional。

{
  tools: {
    profile: 'coding',
    deny: ['group:runtime'],
  },
  channels: {
    whatsapp: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime', 'write', 'edit', 'apply_patch'] },
        },
      },
    },
    telegram: {
      groups: {
        '*': {
          tools: { deny: ['group:runtime'] },
          toolsBySender: {
            '123456789': { alsoAllow: ['write'] },
          },
        },
      },
    },
  },
}

B.6 持久化与记忆模板

持久化与记忆通常分为两部分：会话状态与长期记忆。https://docs.openclaw.ai 的文档对会话与记忆的文件布局、索引方式与裁剪策略有明确描述，建议先通读再落地配置：会话、记忆、上下文裁剪、压缩。

下面示例展示了常见的“会话与压缩”配置骨架。重点是把会话行为与压缩策略显式化，便于验收与排障。

{
  session: {
    // 会话的重置、作用域与清理策略
  },
  agents: {
    defaults: {
      // 记忆与上下文压缩的核心开关与策略
      memory: {
        enabled: true
      },
      contextPruning: {
        enabled: true
      },
      compaction: {
        enabled: true,
        memoryFlush: true
      }
    }
  }
}

验收建议以“可观测”为前提：优先通过 status --deep 与日志确认会话与记忆相关配置是否被加载，避免只靠主观对话观察。

openclaw status --deep
openclaw logs --follow --json

B.7 技能文件模板

技能体系用于固化流程方法，建议按目录组织为 ~/.openclaw/skills/<skill-name>/SKILL.md。技能的格式与加载方式见官方说明：技能概念、技能文档。

下面给出一个可直接复用的 SKILL.md 模板。

# 渠道排障

本节提供了相应的配置。

## 适用场景

渠道不回消息、配对失败、群聊不触发。

## 步骤

1. 运行 doctor。
2. 运行 channels status --probe。
3. 根据日志中的 traceId 回放定位。

## 输出要求

输出必须包含：命令、预期输出、异常分支与下一步。

技能是方法与步骤，不是运行时权限边界；高风险能力仍应由工具策略与沙箱控制。

B.8 使用说明与验收建议

配置与扩展的验收建议遵循“先自检、再探针、最后做真实交互”的顺序：

• 自检：先确保依赖与配置结构无误。

• 探针：再确认模型与渠道可用。

• 交互：最后再用少量真实消息验证路由、门控与工具策略。

B.9 历史版本字段迁移映射表

OpenClaw 采取严格的 Schema 校验机制，当您将旧版本配置文件带入新版本系统时，通常会被 Gateway 拒绝启动。遇到此类情况时，您可以通过 openclaw doctor --fix 尝试自动修复，或是参考下方给出的常见漂移映射手动修改：

老配置形态 / 遗留字段	对应的新配置形态 / 最佳实践	备注
diagnostics.logPath	logging.file	日志全系迁移至统一 logging 命名空间管理。
diagnostics.redact / maskedEnv	logging.redactSensitive / redactPatterns	旧版中被混在诊断对象中，目前剥离到专注脱敏的日志对象层级。
配置中直写加密口令 / API Key	结合 ${VAR} 的内联环境变量替换或是 SecretRef 对象	出于审计与泄漏防护的考量，生产环境已不再建议将值硬编码在 JSON 当中。
ENV: 开头的魔术字符串	${VAR_NAME} 字符串插值形式	原先 ENV: 为老版本遗留或口头契约，当前标准执行器将依据 ${} 来挂接运行时环境。
routing.rules	messages.groupChat (群组), 相关 Policy 配置	有效管理面逐渐从独立路由对象重定向到了各渠道内的 Policy 选项层。