OpenClaw 核心配置完整指南

       第一大模块：Agents 配置（核心员工守则）
   

   

这是最核心的部分，决定了 AI 的基本行为。在 Agents.Defaults 下面有几个关键字段：

• Workspace：设置 AI 的工作目录，默认是用户目录下的 ~/.OpenClaw/Workspace，这个目录下存放 AI 的行为说明（Prompt）和用户信息文件。
• Model：设置使用哪个 AI 模型，格式必须是 提供商/模型名，比如 anthropic/claude-3-opus，还可以设置 Fallbacks 备用模型列表。
• Heartbeat（心跳任务）：设置 AI 定期主动发消息给你。every 字段设置间隔，比如 30m 是每 30 分钟。target 字段设置发给哪个渠道，可以是 last（最后联系的渠道），或者指定 telegram 等。
• Timeout Seconds：设置 AI 任务最长运行时间，默认 600 秒（10 分钟）。

       第二大模块：Providers 配置（服务商密钥）
   

   

用来填写各 AI 服务商的 API 密钥。

• 在 Models.Providers 下面，Anthropic 字段填 Claude 的密钥，OpenAI 字段填 GPT 的密钥，Deepseek 字段填 Deepseek 的密钥，还支持自定义提供商。
• 推荐做法：用环境变量引用，而不是直接写明文。格式是美元符号加花括号加变量名，比如 ${ANTHROPIC_API_KEY}。

       第三大模块：Channels 配置（通信渠道）
   

配置 AI 通过哪些渠道和你聊天。每个渠道都有两个通用基础字段：enabled 设为 true 表示开启，dm_policy 控制谁能给 AI 发私信。

• DM Policy 的四个值：
             
  
  
  •                
  • default：默认模式，新用户需要配对授权才能使用。
  
  
  •                
  • allowlist：只允许 allow_from 白名单里的用户使用。
  
  
  •                
  • open：允许所有人，需要配合 allow_from 信号控制。
  
  
  •                
  • disabled：完全关闭私信
• 各渠道详细配置举例：
             
  
  
  •                
  • Telegram：需要填 bot_token（机器人令牌）。
  
  
  •                
  • WhatsApp：直接扫码不需要令牌，只需配置 allow_from 填手机号。
  
  
  •                
  • Discord：需要填 token（机器人令牌）。
  
  
  •                
  • 飞书：需要填 app_id 和 app_secret。
• 群聊控制：groups 字段设置哪些群组允许使用。require_mention 设为 true 表示必须 @机器人才回应。group_access 可设置开放、白名单或关闭模式。

       第四大模块：Gateway 配置（网关门卫）
   

    控制网关服务器本身的行为。

• Port：监听端口，默认 18789。
• Auth Token：访问令牌，用于 API 鉴权、Reload 重载、Mod 控制。
• Reload Mode：控制热重载方式。hybrid 是默认自动处理；hot 只重载安全变更；restart 每次都重启；off 关闭自动重载。
• *注意：Gateway 配置修改需要重启服务，其他大部分配置都支持热重载。

       第五大模块：Session 配置（会话上下文）
    

• DM Scope：控制隔离范围。main 是所有人共享，peer 是每人单独会话，per_channel_peer 是每渠道每人独立（多用户推荐）。
• Reset：重置策略。mode 可设 daily 每天重置，at_hour 设重置时间，idle_minutes 设多少分钟不活跃后重置。

       第六大模块：Tools 配置（AI 工具箱）
    

• Web Search：网页搜索，填入 Brave Search 等 API 密钥，让 AI 联网。
• Computer：控制 AI 能否操作你的电脑（截图、点击等），默认关闭。
• Bash：允许 AI 执行 shell 命令，安全敏感，谨慎开启。
• Elevated：高权限操作总开关，allow_from 设置允许哪些用户触发。

       第七大模块：Cron 和 Hooks 配置（自动化任务）
    

• Cron：enabled 设为 true 开启定时任务，具体任务在 Cron 目录下配置。
• Hooks：开启 HTTP 回调端点，让外部服务能向 OpenClaw 发消息。包含 hooks_token（鉴权）和 hooks_path（监听路径）。

       第八大模块：ENV 配置（环境变量）
    

• 可以直接写变量（如 OPENROUTER_API_KEY="你的密钥"），或用 vars 嵌套。
• 更好的做法：把密钥写在 .OpenClaw 目录下的 .env 文件里，然后在配置里用 ${变量名} 引用。这样配置文件能安全分享，不泄露密钥。