学了个寂寞

Appearance

配置指南 ​

OpenClaw 从 ~/.openclaw/openclaw.json 读取配置（格式：JSON5，支持注释和末尾逗号）。

如果文件不存在，OpenClaw 使用安全默认值。常见的配置需求：

  • 接入渠道，控制哪些用户可以联系 Bot
  • 设置 AI 模型、工具、沙箱或自动化（定时任务、Hooks）
  • 调整会话、媒体、网络或界面

最小配置 ​

json5
// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

如何编辑配置 ​

交互式向导 ​

bash
openclaw onboard    # 完整初始化向导
openclaw configure  # 配置向导

命令行（单行操作） ​

bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset tools.web.search.apiKey

控制面板 ​

打开 http://127.0.0.1:18789，进入 Config 标签页，有图形化表单编辑器，也有原始 JSON 编辑器。

直接编辑文件 ​

直接修改 ~/.openclaw/openclaw.json，Gateway 监控文件变化并自动应用（见热重载）。

严格验证 ​

警告：OpenClaw 只接受完全符合 Schema 的配置。未知字段、类型错误或非法值都会导致 Gateway 拒绝启动。唯一的例外是根级别的 $schema 字段。

配置验证失败时：

  • Gateway 不会启动
  • 只有诊断命令可用（openclaw doctor、openclaw logs、openclaw health、openclaw status）
  • 运行 openclaw doctor 查看具体问题
  • 运行 openclaw doctor --fix（或 --yes）自动修复

常用配置场景 ​

接入渠道（WhatsApp、Telegram、Discord 等） ​

每个渠道在 channels.<渠道名> 下配置。所有渠道共用相同的接入策略模式：

json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // 仅 allowlist/open 时有效
    },
  },
}

dmPolicy 取值：

  • "pairing"（默认）：未知发送者需通过一次性配对码授权
  • "allowlist"：只允许 allowFrom 中的用户
  • "open"：允许所有人（需同时设置 allowFrom: ["*"]）
  • "disabled"：忽略所有私信

选择和配置 AI 模型 ​

json5
{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-5": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}
  • 模型引用格式：provider/model（例如 anthropic/claude-opus-4-6）
  • agents.defaults.models 定义模型目录，也作为 /model 命令的可选列表

会话管理 ​

json5
{
  session: {
    dmScope: "per-channel-peer",  // 推荐多用户场景
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope 取值：main（共享）| per-peer | per-channel-peer | per-account-channel-peer

启用沙箱 ​

在隔离的 Docker 容器中运行 Agent 任务：

json5
{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

首次使用前需构建沙箱镜像：scripts/sandbox-setup.sh

配置心跳（定时签到） ​

json5
{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}
  • every：时间字符串（30m、2h），设 0m 禁用
  • target：last | whatsapp | telegram | discord | none

配置定时任务（Cron） ​

json5
{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

配置 Webhook（Hooks） ​

json5
{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

安全提示：所有 Webhook 载荷内容应视为不可信输入，不要开启 allowUnsafeExternalContent 等安全旁路标志。

多 Agent 路由 ​

json5
{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

拆分多个配置文件（$include） ​

json5
// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}
  • 单文件：替换所在对象
  • 数组：按顺序深合并（后者优先）
  • 支持最多 10 层嵌套
  • 路径相对于引用它的文件解析

热重载 ​

配置类别涉及字段是否需要重启
渠道channels.*否
Agent 与模型agent、agents、models、routing否
自动化hooks、cron、agent.heartbeat否
会话与消息session、messages否
工具与媒体tools、browser、skills、audio否
Gateway 服务器gateway.*（端口、绑定、认证、TLS）是
基础设施discovery、canvasHost、plugins是

注意：gateway.reload 和 gateway.remote 字段的变更不会触发重启。

配置热重载模式：

json5
{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

环境变量 ​

OpenClaw 从父进程 + 以下来源读取环境变量：

  • 当前目录的 .env（如果存在）
  • ~/.openclaw/.env（全局兜底）

两者均不覆盖已存在的环境变量。也可以在配置中直接设置：

json5
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

配置值中引用环境变量 ​

json5
{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

规则：

  • 只识别大写格式：[A-Z_][A-Z0-9_]*
  • 缺失或为空的变量在加载时报错
  • 转义：$${VAR} 输出字面量 ${VAR}

完整配置示例 ​

最小配置 ​

json5
{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

推荐入门配置 ​

json5
{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

多平台接入 ​

json5
{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["123456789012345678"] },
    },
  },
}

多用户安全 DM 模式 ​

如果有多个用户可以 DM 你的 Bot，建议启用安全 DM 模式，让不同用户的对话不共享上下文：

json5
{
  session: { dmScope: "per-channel-peer" },
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },
  },
}

工具推荐：JS开发的工具大全

Copyright © 2026 地豆 蜀ICP备2021007188号 | 关于本站 | 隐私政策