OpenClaw 配置全景指南：从入门到精通

jack.yang

发布于 2026-03-13 08:24:57

100

OpenClaw 的配置系统以灵活和强大著称，但丰富的选项也让新手望而却步。本文是一份实战导向的配置百科全书，收录了从“最小可用”到“企业级集群”的所有关键配置模式。

阅读建议

新手：直接从快速入门开始。
进阶：参考完整配置详解理解各模块作用。
场景化：在常见场景模板中查找你的具体需求。
避坑：务必查看常见错误与修正。

快速入门配置

1. 绝对最小配置 (Hello World)

只需指定工作区和允许的 WhatsApp 号码，即可启动最基础的 Bot。

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

保存至 ~/.openclaw/openclaw.json 后，即可从该号码向 Bot 发送私信。

2. 推荐新手配置 (Best Practice Starter)

包含身份设定、模型选择及群组行为控制，适合个人日常使用。

{
  identity: {
    name: "小爪",
    theme: "乐于助人的助手",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },  // 群组中需要@提及才回复
    },
  },
}

完整配置示例（带详细注释）

格式说明：以下使用 JSON5 格式，支持注释 // 和尾随逗号 ,。普通 JSON 同样有效（需去除注释）。

{
  // ========== 1. 环境变量管理 ==========
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,      // 继承宿主机的 shell 环境变量
      timeoutMs: 15000,    // 获取环境变量的超时时间 (15 秒)
    },
  },

  // ========== 2. 认证与凭证管理 ==========
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",       // 使用 OAuth 登录
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
    },
    order: {
      // 定义提供商的尝试顺序 (优先 OAuth，失败则试 API Key)
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
    },
  },

  // ========== 3. 机器人身份设定 ==========
  identity: {
    name: "小懒",
    theme: "乐于助人的树懒",
    emoji: "🦥",
  },

  // ========== 4. 日志与监控 ==========
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",  // 自动脱敏工具输出中的敏感信息 (如密码/Key)
  },

  // ========== 5. 消息交互格式 ==========
  messages: {
    messagePrefix: "[openclaw]",  // 发送消息时的前缀
    responsePrefix: ">",           // 回复内容的前缀
    ackReaction: "👀",             // 收到消息时的即时表情反应
    ackReactionScope: "group-mentions",  // 仅在群组@提及时触发反应
  },

  // ========== 6. 路由策略与消息队列 ==========
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "小爪"],  // 触发响应的关键词/模式
      historyLimit: 50,                         // 上下文历史消息条数限制
    },
    queue: {
      mode: "collect",            // 收集模式：短时间内多条消息合并处理
      debounceMs: 1000,           // 防抖时间：等待 1 秒无新消息再处理
      cap: 20,                    // 队列容量上限：最多收集 20 条
      drop: "summarize",           // 超出容量时的策略：自动总结丢弃
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
      },
    },
  },

  // ========== 7. 多媒体处理能力 ==========
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,  // 最大 20MB
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,  // 最大 50MB
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // ========== 8. 会话生命周期管理 ==========
  session: {
    scope: "per-sender",           // 核心策略：每个发送者独立会话
    reset: {
      mode: "daily",                // 重置模式：每日重置
      atHour: 4,                    // 具体时间：凌晨 4 点
      idleMinutes: 60,               // 空闲重置：空闲 1 小时后重置
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },  // Discord 特例：每周重置
    },
    resetTriggers: ["/new", "/reset"],  // 用户指令触发重置
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",          // 30 天后清理旧会话
      maxEntries: 500,            // 单会话最多保留 500 条消息
      rotateBytes: "10mb",        // 日志轮转阈值
      maxDiskBytes: "500mb",      // 磁盘占用上限
    },
    typingIntervalSeconds: 5,      // 发送打字状态指示器的间隔
  },

  // ========== 9. 多平台频道详细配置 ==========
  channels: {
    // --- WhatsApp ---
    whatsapp: {
      dmPolicy: "pairing",                    // 私信策略：需配对
      allowFrom: ["+15555550123"],              // 白名单号码
      groupPolicy: "allowlist",                 // 群组策略：白名单
      groupAllowFrom: ["+15555550123"],          // 群组内允许的用户
      groups: { "*": { requireMention: true } }, // 通配符：所有群需@提及
    },

    // --- Telegram ---
    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    // --- Discord ---
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },

    // --- Slack ---
    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { allow: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,  // 命令响应仅发起者可见
      },
    },
  },

  // ========== 10. Agent 运行时核心配置 ==========
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "Asia/Shanghai",
      
      // --- 模型策略 ---
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },

      // --- 功能开关 ---
      thinkingDefault: "low",          // 思考过程详细度 (low/medium/high)
      verboseDefault: "off",            // 详细输出默认关闭
      elevatedDefault: "on",             // 提升权限默认开启 (谨慎使用)
      
      // --- 资源限制 ---
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      maxConcurrent: 3,                  // 最大并发会话数

      // --- 心跳保活 (防休眠) ---
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-5",
        target: "last",
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },

      // --- 记忆与搜索 ---
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },

      // --- 沙箱安全隔离 ---
      sandbox: {
        mode: "non-main",                // 非主要 agent 启用沙箱
        perSession: true,                  // 每会话独立沙箱环境
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",                  // 禁用网络访问
          user: "1000:1000",
        },
        browser: {
          enabled: false,                   // 禁用浏览器工具
        },
      },
    },
  },

  // ========== 11. 工具权限控制 ==========
  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,    // 执行超过 10 秒自动转入后台
      timeoutSec: 1800,       // 最大执行时间 30 分钟
      cleanupMs: 1800000,     // 完成后 30 分钟清理记录
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["123456789012345678"],
      },
    },
  },

  // ========== 12. 自定义模型提供商集成 ==========
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // ========== 13. 定时任务 (Cron) ==========
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },

  // ========== 14. Webhooks 外部集成 ==========
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
        to: "+15555550123",
      },
    ],
  },

  // ========== 15. 网关网络与安全配置 ==========
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",           // 仅本地回环接口访问
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
  },
}

常见场景配置模板

1. 多平台统一助手

目标：同时启用 WhatsApp、Telegram、Discord，统一管理。

{
  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"] },
    },
  },
}

2. 安全私信模式 (多人共享收件箱)

目标：允许多人私信，但严格隔离每个人的会话上下文，防止串聊。

{
  // 关键：设置 dmScope 为 per-channel-peer，确保每人独立会话
  session: { dmScope: "per-channel-peer" },

  channels: {
    // WhatsApp 多人收件箱
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Discord 多人收件箱
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["123456789012345678", "987654321098765432"] },
    },
  },
}

3. OAuth + API 密钥双保险

目标：优先使用订阅制 (OAuth)，失败时自动降级为按量付费 (API Key)。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

4. Anthropic 主备 + MiniMax 兜底

目标：构建高可用链路，Anthropic 失效时切换至 MiniMax。

注意：使用前请核实 Anthropic setup-token 的服务条款限制。

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "user@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-opus-4-6",
      fallbacks: ["minimax/MiniMax-M2.5"],
    },
  },
}

5. 工作专用 Bot (受限访问)

目标：仅在 Slack 特定频道响应，且禁用高风险工具。

{
  identity: {
    name: "工作助手",
    theme: "专业助手",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },  // 禁用提升权限
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

6. 纯本地模型部署

目标：完全离线或内网运行，对接 LM Studio / Ollama。

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.5-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

7. 媒体处理专用 Agent

目标：配置大文件处理能力，专用于语音转录和视频分析。

{
  agents: {
    list: [{
      id: "media-agent",
      workspace: "~/.openclaw/media-workspace",
      tools: {
        media: {
          audio: {
            enabled: true,
            maxBytes: 104857600,  // 100MB
            models: [
              { provider: "openai", model: "gpt-4o-mini-transcribe" },
              { type: "cli", command: "whisper", args: ["--model", "large"] }
            ],
          },
          video: {
            enabled: true,
            maxBytes: 524288000,  // 500MB
            models: [{ provider: "google", model: "gemini-1.5-pro" }],
          },
        },
      },
    }],
  },
}

8. 定时任务助手

目标：自动执行日报、周报生成任务。

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    jobs: [
      {
        id: "daily-summary",
        schedule: "0 9 * * *",  // 每天上午 9 点
        to: "+15555550123",
        prompt: "生成昨天的未读消息摘要",
      },
      {
        id: "weekly-report",
        schedule: "0 10 * * 1",  // 每周一上午 10 点
        to: "+15555550123",
        prompt: "生成上周的工作报告",
        timeoutMinutes: 30,
      },
    ],
  },
}

9. Gmail 邮件钩子 (Webhook)

目标：接收 Gmail 推送并自动处理邮件内容。

{
  hooks: {
    enabled: true,
    token: "webhook-secret",
    gmail: {
      account: "my@gmail.com",
      label: "INBOX",
      includeBody: true,
      maxBytes: 20000,
      pushToken: "pubsub-token",
      hookUrl: "https://my-domain.com/hooks/gmail",
    },
    mappings: [
      {
        id: "gmail-processor",
        match: { path: "gmail" },
        action: "agent",
        sessionKey: "gmail:{{messages[0].id}}",
        transform: {
          module: "gmail-processor.js",
          export: "transform",
        },
      },
    ],
  },
}

配置技巧与最佳实践

1. 环境变量分层管理

灵活混合硬编码、变量组和系统环境变量。

{
  env: {
    // 直接定义敏感 Key
    OPENAI_API_KEY: "sk-...",
    
    // 使用变量组管理同类 Key
    vars: {
      ANTHROPIC_API_KEY: "sk-...",
    },
    
    // 继承 Shell 环境 (适合 Docker/K8s 部署)
    shellEnv: {
      enabled: true,
      timeoutMs: 5000,
    },
  },
}

2. 多 Agent 分工协作

定义不同角色的 Agent，分配不同的模型和权限。

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
    },
    list: [
      {
        id: "personal",
        identity: { name: "个人助手" },
        model: { primary: "anthropic/claude-opus-4-6" },
        tools: { allow: ["exec", "read", "write", "browser"] },
      },
      {
        id: "work",
        identity: { name: "工作助手" },
        model: { primary: "openai/gpt-4" },
        tools: { deny: ["browser", "exec"] }, // 工作区禁用执行
        sandbox: { mode: "all" },
      },
      {
        id: "public",
        identity: { name: "客服" },
        model: { primary: "openrouter/mistral-7b" },
        tools: { deny: ["*"] },  // 公共区无任何工具权限
        session: { dmScope: "per-channel-peer" },
      },
    ],
  },
}

3. 深度安全加固

实施最小权限原则和强制沙箱。

{
  // 1. 最小化权限
  tools: {
    deny: ["gateway", "cron", "sessions_spawn", "sessions_send"],
    exec: { security: "ask", host: "sandbox" },
  },

  // 2. 严格访问控制
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
    },
  },

  // 3. 强制沙箱隔离
  agents: {
    defaults: {
      sandbox: {
        mode: "all",
        docker: { network: "none" }, // 彻底断网
      },
    },
  },

  // 4. 审计日志
  logging: {
    level: "debug",
    file: "/var/log/openclaw/audit.log",
    redactSensitive: "all",
  },
}

常见错误与解决方案

错误 1：`dmPolicy: "open"` 但缺少通配符

现象：配置了开放策略，但非白名单用户仍无法发消息。

错误 2：多人共享导致会话串扰

现象：A 用户说的话，B 用户能接着聊，上下文混乱。

结语

OpenClaw 的配置系统如同搭积木，简单起步，无限扩展。

从简开始：先用最小配置跑通流程。
安全第一：始终配置 allowFrom 和 sandbox。
分层管理：利用 defaults 设置全局基准，用 list 覆盖特定需求。
验证先行：每次修改后，运行 openclaw doctor 检查配置合法性。

本文参与腾讯云自媒体同步曝光计划，分享自作者个人站点/博客。

原始发表：2026-03-12，如有侵权请联系 cloudcommunity@tencent.com 删除

管理

本文分享自作者个人站点/博客前往查看

如有侵权，请联系 cloudcommunity@tencent.com 删除。

本文参与腾讯云自媒体同步曝光计划，欢迎热爱写作的你一起参与！

登录后参与评论

0 条评论

热度