02-配置参考

概述

OpenClaw 从 ~/.openclaw/openclaw.json 读取可选的 JSON5 配置（允许注释 + 尾随逗号）。

如果文件缺失，OpenClaw 使用安全的默认设置（嵌入式 Pi 代理 + 每发送者会话 + 工作区 ~/.openclaw/workspace）。

您通常只需要配置来：

• 限制谁可以触发机器人（channels.whatsapp.allowFrom、channels.telegram.allowFrom 等）
• 控制群组允许列表 + 提及行为（channels.whatsapp.groups、channels.telegram.groups 等）
• 自定义消息前缀（messages）
• 设置代理的工作区（agents.defaults.workspace 或 agents.list[].workspace）
• 调整嵌入式代理默认值（agents.defaults）和会话行为（session）
• 设置每个代理的身份（agents.list[].identity）

严格配置验证

OpenClaw 仅接受与模式完全匹配的配置。未知键、格式错误的类型或无效值会导致 Gateway 拒绝启动以确保安全。

验证失败时：

• Gateway 不启动
• 仅允许诊断命令（例如 openclaw doctor、openclaw logs 等）
• 运行 openclaw doctor 查看具体问题
• 运行 openclaw doctor --fix 应用迁移/修复

最小配置（推荐起点）

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

常用选项

环境变量 + .env

OpenClaw 从父进程（shell、launchd/systemd、CI 等）读取环境变量。

此外，它加载：

• 当前工作目录中的 .env（如果存在）
• ~/.openclaw/.env 中的全局回退 .env

两个 .env 文件都不会覆盖现有环境变量。

环境变量替换

您可以使用 ${VAR_NAME} 语法直接在配置中引用环境变量。

{
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

多代理路由（agents.list + bindings）

在一个 Gateway 中运行多个隔离的代理（单独的工作区、agentDir、会话）。

入站消息通过 bindings 路由到代理。

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

频道配置

WhatsApp

{
  "channels": {
    "whatsapp": {
      "enabled": true,
      "dmPolicy": "pairing",
      "allowFrom": ["+15555550123"],
      "textChunkLimit": 4000,
      "chunkMode": "length",
      "mediaMaxMb": 50
    }
  }
}

Telegram

{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "your-bot-token",
      "dmPolicy": "pairing",
      "groups": { "*": { "requireMention": true } }
    }
  }
}

Discord

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "your-bot-token",
      "dm": {
        "enabled": true,
        "policy": "pairing"
      },
      "guilds": {
        "YOUR_GUILD_ID": {
          "channels": {
            "general": { "allow": true }
          }
        }
      }
    }
  }
}

Slack

{
  "channels": {
    "slack": {
      "enabled": true,
      "botToken": "xoxb-...",
      "appToken": "xapp-...",
      "dm": {
        "enabled": true,
        "policy": "pairing"
      }
    }
  }
}

全局配置参考

日志记录

{
  "logging": {
    "level": "info",
    "file": "/tmp/openclaw/openclaw.log",
    "consoleLevel": "info",
    "consoleStyle": "pretty",
    "redactSensitive": "tools"
  }
}

会话

{
  "session": {
    "dmScope": "main",
    "reset": {
      "mode": "daily",
      "atHour": 4
    }
  }
}

消息队列

{
  "messages": {
    "queue": {
      "mode": "collect",
      "debounceMs": 1000,
      "cap": 20
    }
  }
}

来源：https://docs.openclaw.ai/gateway/configuration