附录B：配置模板与样例

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

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

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

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

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

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

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

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

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

  diagnostics: {
    redact: true,
    logPath: "/tmp/openclaw/openclaw-%DATE%.log",
    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: "ENV:TELEGRAM_BOT_TOKEN",

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

      groupPolicy: "disabled",
    },
  },
}

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

B.5 工具治理模板（channels..groups..tools + allow/deny）

工具治理的官方配置以 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: ['shell.*'],
  },
  channels: {
    whatsapp: {
      groups: {
        '*': {
          tools: { deny: ['shell.*', 'fs.write*', 'fs.delete*'] },
        },
      },
    },
    telegram: {
      groups: {
        '*': {
          tools: { deny: ['shell.*'] },
          toolsBySender: {
            '123456789': { alsoAllow: ['fs.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 使用说明与验收建议

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

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

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

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

openclaw doctor
openclaw health --json
openclaw status --deep
openclaw channels status --probe
openclaw models status --check