OpenClaw 配置参考大全：从入门到精通

jack.yang

发布于 2026-03-13 08:23:10

1120

OpenClaw 拥有超过 200 个可配置项，构建了极其灵活的系统。本文是 ~/.openclaw/openclaw.json 的完整字段参考手册。无论你是初次上手的新手，还是查找特定参数的高级用户，都能在此找到答案。

格式说明

配置文件采用 JSON5 格式，支持注释 // 和尾随逗号 ,。
所有字段均为可选。省略时，OpenClaw 将使用安全的默认值。
敏感信息建议使用环境变量 ${VAR} 或 SecretRef 引用。

目录索引

频道配置 (Channels)
Agent 默认配置
多 Agent 路由
会话管理
消息处理
工具权限
模型提供商
网关网络
Webhooks 集成
定时任务
安全与认证
密钥与环境变量
日志与调试
最佳实践与避坑

频道配置 (Channels)

每个频道在其配置节存在时自动启动（除非显式设置 enabled: false）。

通用访问控制策略

所有频道均支持私信（DM）和群组（Group）两级策略：

注意

配对码有效期为 1 小时。
每个频道待处理的私信配对请求上限为 3 个。

频道级模型覆盖

使用 channels.modelByChannel 将特定频道 ID 强制绑定到特定模型：

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

WhatsApp 配置

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // 开启蓝色已读回执
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}

多账户 WhatsApp 支持：

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {},
      },
    },
  },
}

Telegram 配置

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "保持答案简洁。",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "请勿跑题。",
            },
          },
        },
      },
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      streaming: "partial", // off | partial | block | progress
      mediaMaxMb: 100,
    },
  },
}

Discord 配置

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "简短回答即可。",
            },
          },
        },
      },
      historyLimit: 20,
      streaming: "off",
      maxLinesPerMessage: 17,
    },
  },
}

Slack 配置

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      channels: {
        "#general": {
          allow: true,
          requireMention: true,
          users: ["U123"],
          skills: ["docs"],
        },
      },
      historyLimit: 50,
      replyToMode: "off",
      slashCommand: {
        enabled: true,
        name: "openclaw",
        ephemeral: true,
      },
      streaming: "partial",
      mediaMaxMb: 20,
    },
  },
}

Agent 默认配置

基础运行时设置

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      repoRoot: "~/Projects/openclaw", // 可选，显示在系统提示中
      skipBootstrap: false,
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 150000,
      userTimezone: "Asia/Shanghai",
      timeFormat: "auto", // auto | 12 | 24
    },
  },
}

模型策略配置

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.5": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      maxConcurrent: 3,
    },
  },
}

心跳检测 (防休眠)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        model: "openai/gpt-5.2-mini",
        to: "+15555550123",
        directPolicy: "allow", // allow | block
        prompt: "读取 HEARTBEAT.md 文件...",
        ackMaxChars: 300,
      },
    },
  },
}

沙箱安全隔离

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          memory: "1g",
          cpus: 1,
        },
        browser: {
          enabled: false,
        },
      },
    },
  },
}

多 Agent 路由

运行多个隔离的 Agent 实例，并根据规则路由消息：

{
  agents: {
    list: [
      { 
        id: "home", 
        default: true, 
        workspace: "~/.openclaw/workspace-home",
        identity: {
          name: "家庭助手",
          emoji: "🏠",
        }
      },
      { 
        id: "work", 
        workspace: "~/.openclaw/workspace-work",
        identity: {
          name: "工作助手",
          emoji: "💼",
        }
      },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

Agent 访问权限示例

完全访问（无沙箱）：

{
  id: "personal",
  workspace: "~/.openclaw/workspace-personal",
  sandbox: { mode: "off" },
}

只读工具 + 只读工作区：

{
  id: "family",
  sandbox: { mode: "all", workspaceAccess: "ro" },
  tools: {
    allow: ["read"],
    deny: ["write", "edit", "apply_patch", "exec"],
  },
}

仅消息（无文件系统访问）：

{
  id: "public",
  sandbox: { mode: "all", workspaceAccess: "none" },
  tools: {
    allow: ["sessions_list", "sessions_send"],
    deny: ["read", "write", "exec", "browser"],
  },
}

会话管理

{
  session: {
    scope: "per-sender",
    dmScope: "per-channel-peer", // main | per-peer | per-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetTriggers: ["/new", "/reset"],
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      maxDiskBytes: "500mb",
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

消息处理

{
  messages: {
    responsePrefix: "🦞",
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | queue
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
    },
    inbound: {
      debounceMs: 2000, // 消息防抖
    },
  },
}

文本转语音 (TTS)

{
  messages: {
    tts: {
      auto: "off", // off | always | inbound | tagged
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      elevenlabs: {
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
        },
      },
      openai: {
        voice: "alloy",
      },
    },
  },
}

工具权限

工具配置文件 (Profiles)

tools.profile 设置基础允许列表：

{
  tools: {
    profile: "coding",
    allow: ["browser"],
    deny: ["canvas"],
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

提升权限 (Elevated)

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123"],
      },
    },
  },
}

后台执行配置

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
    },
  },
}

媒体处理配置

{
  tools: {
    media: {
      concurrency: 2,
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

模型提供商

自定义提供商集成

{
  models: {
    mode: "merge", // merge | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "${LITELLM_KEY}",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        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,
          },
        ],
      },
    },
  },
}

常见提供商示例

Cerebras (GLM 4.7)：

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "cerebras/zai-glm-4.7" },
    },
  },
  models: {
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
      },
    },
  },
}

本地模型 (LM Studio)：

{
  agents: {
    defaults: {
      model: { primary: "lmstudio/minimax-m2.5-gs32" },
    },
  },
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
      },
    },
  },
}

网关网络

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback", // loopback | lan | tailnet | custom
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "remote-token",
    },
    trustedProxies: ["10.0.0.1"],
  },
}

Webhooks 集成

基础 Webhook 配置

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "来自：{{messages[0].from}}\n主题：{{messages[0].subject}}",
        deliver: true,
        channel: "last",
      },
    ],
  },
}

Gmail 深度集成

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
    },
  },
}

定时任务

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
    jobs: [
      {
        id: "daily-summary",
        schedule: "0 9 * * *", // 每天上午 9 点
        to: "+15555550123",
        prompt: "生成昨天的未读消息摘要",
      },
    ],
  },
}

技能插件 (Skills)

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
      },
      peekaboo: { enabled: true },
    },
  },
}

浏览器配置

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // 允许内网访问，需谨慎
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
    },
  },
}

密钥与环境变量

环境变量管理

内联定义：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

变量替换 (在任意字符串中使用 ${VAR})：

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

密钥管理 (SecretRef)

SecretRef 对象结构：

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

密钥提供商配置：

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
  },
}

安全与认证

认证存储配置

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { 
        provider: "anthropic", 
        mode: "oauth", 
        email: "me@example.com" 
      },
      "anthropic:work": { 
        provider: "anthropic", 
        mode: "api_key" 
      },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}

身份配置 (Identity)

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "小爪",
          theme: "乐于助人的助手",
          emoji: "🦞",
          avatar: "avatars/clawd.png", // 支持：工作区相对路径、URL 或 data URI
        },
      },
    ],
  },
}

日志与调试

日志配置

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

配置文件拆分 (`$include`)

使用 $include 将大型配置拆分为多个文件：

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  channels: {
    $include: ["./channels/whatsapp.json5", "./channels/telegram.json5"],
  },
}

配置验证命令

# 检查配置有效性
openclaw doctor

# 自动修复常见问题
openclaw doctor --fix

# 查看详细配置解析结果
openclaw doctor --verbose

最佳实践与避坑

常见配置错误对照表

结语

OpenClaw 的配置系统设计遵循 “最小权限、安全优先、渐进增强” 的核心原则。通过本文的完整参考，你现已掌握：

每个配置字段的详细作用与默认行为。
针对不同场景（个人、团队、企业）的配置模板。
避免常见陷阱的实战技巧。
安全管理敏感信息的最佳实践。

从今天起，尝试从最小配置开始，随着需求的演进逐步构建属于你自己的强大 AI 助手系统吧！

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

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

配置

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

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

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

登录后参与评论

0 条评论

热度