Skip to main content

​
配置 OpenClaw

OpenClaw 会从 ~/.openclaw/openclaw.json 读取一个可选的 JSON5 配置文件。 如果文件不存在,OpenClaw 将使用安全默认值。添加配置的常见原因包括:
  • 连接渠道并控制谁可以给机器人发消息
  • 设置模型、工具、沙箱环境或自动化(定时任务、钩子)
  • 调整会话、媒体、网络或 UI
配置新手? 请先运行 openclaw onboard 进行交互式设置,或查看配置示例指南,获取完整的复制粘贴配置。

​
最小配置

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

​
编辑配置的方式

openclaw onboard       # 完整设置向导
openclaw configure     # 配置向导

​
严格校验

OpenClaw 仅接受完全符合 schema 的配置。未知键、类型错误或无效值都会导致 Gateway 拒绝启动。唯一的根级例外是 $schema(字符串),允许编辑器附加 JSON Schema 元数据。
校验失败时:
  • Gateway 不启动
  • 仅诊断命令可用(openclaw doctor、openclaw logs、openclaw health、openclaw status)
  • 运行 openclaw doctor 查看具体问题
  • 运行 openclaw doctor --fix(或 --yes)自动修复

​
常见配置任务

​
设置渠道

每个渠道都有自己的配置节,位于 channels.<provider> 下。所有渠道共享相同的私信(DM)策略模式: 
{
  "channels": {
    "telegram": {
      "enabled": true,
      "botToken": "123:abc",
      "dmPolicy": "pairing",
      "allowFrom": ["tg:123"]
    }
  }
}
支持的渠道:
  • WhatsApp — channels.whatsapp
  • Telegram — channels.telegram
  • Discord — channels.discord
  • Slack — channels.slack
  • Signal — channels.signal
  • iMessage — channels.imessage
  • Google Chat — channels.googlechat
  • Mattermost — channels.mattermost
  • MS Teams — channels.msteams

​
选择并配置模型

设置主模型及可选的备用模型: 
{
  "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"
        }
      }
    }
  }
}
要点:
  • agents.defaults.models 定义模型目录并作为 /model 的白名单
  • 模型引用格式为 provider/model(如 anthropic/claude-opus-4-6)
  • agents.defaults.imageMaxDimensionPx 控制转录/工具图像的缩放(默认 1200)

​
控制谁可以给机器人发消息

私信访问通过渠道的 dmPolicy 控制:
  • "pairing"(默认):未知发送者获得一次性配对码用于批准
  • "allowlist":仅允许 allowFrom 中的发送者(或配对的允许存储)
  • "open":允许所有入站私信(需设为 allowFrom: ["*"])
  • "disabled":忽略所有私信
群组请使用 groupPolicy + groupAllowFrom 或渠道特定的允许列表。

​
配置会话与重置

会话控制对话连续性和隔离: 
{
  "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
  • threadBindings:线程绑定的全局默认,会话路由

​
启用沙箱环境

在隔离的 Docker 容器中运行代理会话: 
{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "scope": "agent"
      }
    }
  }
}
请先构建镜像:scripts/sandbox-setup.sh

​
设置心跳(周期性签到)

{
  "agents": {
    "defaults": {
      "heartbeat": {
        "every": "30m",
        "target": "last"
      }
    }
  }
}
  • every:时间间隔字符串(如 30m、2h),设置 0m 禁用
  • target:last | whatsapp | telegram | discord | none

​
配置定时任务

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

​
配置多代理路由

运行多个隔离代理,使用独立的工作区和会话: 
{
  "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"
      }
    }
  ]
}

​
配置热重载

Gateway 会监视 ~/.openclaw/openclaw.json 并自动应用更改 — 大多数设置无需手动重启。

​
重载模式

模式行为
hybrid(默认)安全更改即时热应用。关键信息变更自动重启。
hot仅热应用安全更改。需要重启时记录警告,由您负责重启。
restart任何配置变更(安全或非安全)均重启 Gateway。
off关闭文件监视。变更仅在下次手动重启时生效。
{
  "gateway": {
    "reload": {
      "mode": "hybrid",
      "debounceMs": 300
    }
  }
}

​
哪些更改热应用,哪些需要重启

大部分字段可热应用且无停机。hybrid 模式会自动处理需要重启的更改。
分类字段需重启?
渠道channels.*、web(WhatsApp)否
代理与模型agent, agents, models, routing否
自动化hooks, cron, agent.heartbeat否
会话与消息session, messages否
工具与媒体tools, browser, skills, audio, talk否
UI 与杂项ui, logging, identity, bindings否
Gateway 服务器gateway.*(端口、绑定、认证、tailscale、TLS、HTTP)是
基础架构discovery, canvasHost, plugins是
gateway.reload 和 gateway.remote 是例外——更改它们不会触发重启。

​
环境变量

OpenClaw 会读取父进程的环境变量,以及:
  • 当前工作目录下的 .env(如果存在)
  • ~/.openclaw/.env(全局备用)
两者都不会覆盖已有的环境变量。您还可以在配置中设置内联环境变量: 
{
  "env": {
    "OPENROUTER_API_KEY": "sk-or-...",
    "vars": {
      "GROQ_API_KEY": "gsk-..."
    }
  }
}

​
Shell 环境导入(可选)

如果启用且缺少预期的键,OpenClaw 会运行登录 shell,仅导入缺少的键: 
{
  "env": {
    "shellEnv": {
      "enabled": true,
      "timeoutMs": 15000
    }
  }
}
等价环境变量:OPENCLAW_LOAD_SHELL_ENV=1

​
配置值中的环境变量替换

在任何配置字符串中,可以用 ${VAR_NAME} 引用环境变量: 
{
  "gateway": {
    "auth": {
      "token": "${OPENCLAW_GATEWAY_TOKEN}"
    }
  },
  "models": {
    "providers": {
      "custom": {
        "apiKey": "${CUSTOM_API_KEY}"
      }
    }
  }
}
规则:
  • 仅匹配大写名称:[A-Z_][A-Z0-9_]*
  • 缺失或空值在加载时抛错
  • 用 $${VAR} 转义输出字面量
  • 可用于 $include 文件中
  • 内联替换例子:"${BASE}/v1" → "https://api.example.com/v1"

​
拆分配置文件($include)

使用 $include 组织大型配置: 
{
  "gateway": {
    "port": 18789
  },
  "agents": {
    "$include": "./agents.json5"
  },
  "broadcast": {
    "$include": [
      "./clients/a.json5",
      "./clients/b.json5"
    ]
  }
}
要点:
  • 单文件:替换包含对象
  • 文件数组:顺序深度合并(后者覆盖前者)
  • 同级键:合并在包含后,覆盖包含值
  • 嵌套包含:支持最多 10 层深度
  • 相对路径:相对于包含文件解析
  • 错误处理:缺少文件、解析错误和循环包含均有清晰报错

​
下一步

环境变量

了解环境变量加载顺序

更新

保持 OpenClaw 最新