NNNNzs

OpenClaw 使用指南：配置、技巧与踩坑记录

2026年04月02日5 次阅读0 人喜欢
OpenClaw配置踩坑TelegramDiscordDingTalk代理定时任务模型

OpenClaw 使用指南：配置、技巧与踩坑记录

本文档持续更新，记录 OpenClaw 的使用配置、踩坑点和最佳实践。

目录

安装与基础配置

1. OpenClaw 网关管理

bash 复制代码 
# 查看状态
openclaw gateway status

# 启动网关
openclaw gateway start

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

2. 配置文件位置

  • 主配置：~/.openclaw/openclaw.json
  • 工作区：~/.openclaw/workspace/
  • 日志：/tmp/openclaw/openclaw-*.log

3. Gateway 绑定模式

OpenClaw 网关支持多种绑定模式，用于控制网络访问范围：

模式 说明 适用场景
loopback 只监听 127.0.0.1 仅本机访问
lan 局域网可访问 同一局域网内设备
tailnet Tailscale 网络 Tailscale VPN 连接
auto 自动选择 智能检测所有接口
custom 自定义地址 手动指定 IP/网卡

配置示例

bash 复制代码 
# 查看当前绑定模式
cat ~/.openclaw/openclaw.json | grep -A 3 '"gateway"'

# 修改绑定模式（需要重启网关生效）
openclaw config set gateway.bind auto
openclaw gateway restart

ZeroTier 场景

如果你使用 ZeroTier 组网（如 192.168.193.194）：

  • 推荐：使用 auto 模式，会自动绑定到 ZeroTier 虚拟网卡
  • 备选：使用 custom 模式，手动指定 ZeroTier IP

多 Agent 配置

OpenClaw 支持多 Agent 模式，每个 Agent 有独立的工作区和配置。

配置示例

json5 复制代码 
{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        workspace: "~/.openclaw/workspace"
      },
      {
        id: "blog-maintainer",
        workspace: "~/.openclaw/workspace-blog",
        agentDir: "~/.openclaw/agents/blog-maintainer/agent"
      }
    ]
  }
}

每个群组独立 Agent

OpenClaw 支持为不同群组配置不同的 Agent 或系统提示词。

方式 1：使用 systemPrompt 区分

json5 复制代码 
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "<YOUR_BOT_TOKEN>",
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": {
          requireMention: false,
          groupPolicy: "open",
          systemPrompt: "你是群组 1 的专属助手，负责处理群组 1 的任务"
        },
        "-1001234567891": {
          requireMention: false,
          groupPolicy: "open",
          systemPrompt: "你是群组 2 的专属助手，负责处理群组 2 的任务"
        }
      }
    }
  }
}

方式 2：使用 agentId 指定不同 Agent

json5 复制代码 
{
  agents: {
    list: [
      { id: "main", default: true, workspace: "~/.openclaw/workspace" },
      { id: "group1-agent", workspace: "~/.openclaw/workspace-group1" },
      { id: "group2-agent", workspace: "~/.openclaw/workspace-group2" }
    ]
  },
  channels: {
    telegram: {
      enabled: true,
      botToken: "<YOUR_BOT_TOKEN>",
      groupPolicy: "allowlist",
      groups: {
        "-1001234567890": {
          requireMention: false,
          agentId: "group1-agent"
        },
        "-1001234567891": {
          requireMention: false,
          agentId: "group2-agent"
        }
      }
    }
  }
}

方式 3：使用 Forum Topics（论坛群组）

如果群组是论坛群组（Supergroup with Topics），可以用 Topic 来区分 Agent：

json5 复制代码 
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "<YOUR_BOT_TOKEN>",
      groups: {
        "-1001234567890": {
          topics: {
            "1": { agentId: "main" },      // General 主题 → main agent
            "3": { agentId: "blog" },      // Blog 主题 → blog 维护 agent
            "5": { agentId: "coder" }      // Code 主题 → coder agent
          }
        }
      }
    }
  }
}

渠道配置

Telegram

基础配置

json5 复制代码 
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "<YOUR_BOT_TOKEN>",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      groups: {
        "*": {
          requireMention: false,
          groupPolicy: "open"
        }
      }
    }
  }
}

群组访问控制

json5 复制代码 
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "<YOUR_BOT_TOKEN>",
      groupPolicy: "allowlist",  // 默认：白名单模式
      groups: {
        "-1001234567890": {
          requireMention: false,
          groupPolicy: "open",  // 所有群成员都能触发
          allowFrom: ["8734062810", "745123456"]  // 只允许指定用户（可选）
        }
      }
    }
  }
}

获取群组 ID

方法 1： 转发消息给 @getidsbot
方法 2： 查看日志：openclaw logs --follow | grep chat.id
方法 3： Bot API：curl "https://api.telegram.org/bot<token>/getUpdates"

常见问题

问题： "This group is not allowed"
原因： 群组 ID 没在 groups 允许列表里
解决：

  1. 获取群组 ID
  2. 添加到 groups 配置
  3. 重启网关

问题： 机器人不响应非 @ 消息
原因： Telegram 隐私模式限制
解决：

  1. BotFather: /setprivacy → Disable
  2. 移除并重新添加机器人到群组

Discord

基础配置

json5 复制代码 
{
  plugins: {
    allow: [
      "telegram",
      "weibo-openclaw-plugin",
      "feishu",
      "discord"
    ]
  },
  channels: {
    discord: {
      enabled: true,
      token: "<YOUR_BOT_TOKEN>",
      groupPolicy: "allowlist",
      guilds: {
        "<YOUR_SERVER_ID>": {
          requireMention: false,
          users: ["<YOUR_USER_ID>"]
        }
      },
      proxy: "http://127.0.0.1:7890"
    }
  }
}

踩坑点

  1. 插件未启用：plugins.allow 里必须添加 discord
  2. 代理配置：使用 HTTP 代理（http://127.0.0.1:7890），不要用 SOCKS5
  3. OAuth2 scope：必须包含 applications.commands

DingTalk（钉钉）

插件安装与配置

钉钉插件需要在 plugins.allow 中启用：

json5 复制代码 
{
  plugins: {
    allow: [
      "telegram",
      "weibo-openclaw-plugin",
      "feishu",
      "discord",
      "dingtalk"  // 添加钉钉插件
    ]
  },
  channels: {
    dingtalk: {
      enabled: true,
      // 钉钉配置（Webhook 等）
    }
  }
}

注意： 插件配置有两种方式：

  • plugins.allow - 启用插件（旧版/兼容模式）
  • plugins.entries - 启用插件（新版推荐）

技能管理

查看已安装技能

bash 复制代码 
ls ~/.openclaw/extensions/

安装新技能

bash 复制代码 
clawhub install <skill-name>

创建自定义技能

参考：~/.openclaw/workspace/skills/

代理配置

OpenClaw 网关代理

OpenClaw 网关的代理配置通过环境变量设置，不是配置文件：

bash 复制代码 
# 在启动脚本或 systemd 服务中设置
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

修改 systemd 服务（推荐）

编辑服务文件：~/.config/systemd/user/openclaw-gateway.service

ini 复制代码 
[Service]
Environment="HTTP_PROXY=http://127.0.0.1:7890"
Environment="HTTPS_PROXY=http://127.0.0.1:7890"

然后重启服务：

bash 复制代码 
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

验证代理配置

bash 复制代码 
# 查看当前进程的环境变量
cat /proc/$(pgrep -f "openclaw-gateway")/environ | tr '\0' '\n' | grep -i proxy

渠道代理配置

某些渠道（如 Discord）支持单独的代理配置：

json5 复制代码 
{
  channels: {
    discord: {
      proxy: "http://127.0.0.1:7890"  // HTTP 代理
    }
  }
}

定时任务

OpenClaw Cron（推荐）

OpenClaw 内置定时任务系统，支持发送系统事件：

json5 复制代码 
{
  cron: {
    jobs: [
      {
        id: "ha-summary",
        schedule: "30 8 * * *",  // 每天 8:30
        action: "systemEvent",
        event: "check_ha_summary_send"
      }
    ]
  }
}

在 HEARTBEAT.md 中处理系统事件

markdown 复制代码 
## OpenClaw 定时任务

当收到 systemEvent "check_ha_summary_send" 时：

1. 读取 /root/.openclaw/workspace/ha-summaries/ 目录下最新的总结文件
2. 通过 Telegram 发送给用户（chat_id: 1784498492）
3. 发送成功后回复确认

系统 Cron（不推荐）

系统 cron 任务（crontab -e）不如 OpenClaw cron 灵活，建议使用 OpenClaw 内置定时任务。

模型配置

OpenRouter 配置

1. 设置 API Key

bash 复制代码 
# 方法 1：环境变量
export OPENROUTER_API_KEY="sk-or-v1-..."

# 方法 2：配置文件
# 编辑 ~/.openclaw/openclaw.json，在 providers 中添加

2. 切换模型

bash 复制代码 
# 当前模型
/openrouter/xiaomi/mimo-v2-pro

# 默认模型
zai/glm-4.7

3. 免费试用提醒

MiMo v2 Pro 免费试用期截止：2026-04-02 12:00PM EST（北京时间 4/3 凌晨 1:00）

如果继续使用，需及时切换到其他模型，避免产生费用。

踩坑记录

坑 1：网关重启导致断连

问题： 自动执行 openclaw gateway restart 会导致与用户的连接断开。

解决： 不要自动重启网关，告诉用户需要执行的命令，让用户手动执行。

坑 2：Discord SOCKS5 代理不兼容 WebSocket

问题： discord gateway error: Proxy connection ended before receiving CONNECT response

解决： 改用 HTTP 代理

json 复制代码 
"proxy": "http://127.0.0.1:7890"

坑 3：Telegram 群组 "This group is not allowed"

原因： 群组 ID 没在 groups 允许列表里。

解决：

  1. 获取群组 ID（转发消息给 @getidsbot）
  2. 添加到 groups 配置
  3. 重启网关

坑 4：敏感信息泄露

问题： Bot Token 等敏感信息明文写在文章里。

解决： 使用占位符 <YOUR_BOT_TOKEN>，不要写实际值。

坑 5：配置热重载

问题： 修改配置后不知道是否需要重启。

解决： OpenClaw 支持配置热重载，部分配置修改后会自动生效。

坑 6：多 Agent 群组配置

问题： 想让不同群组使用不同的 Agent 或系统提示词。

解决：

  • 使用 systemPrompt 为不同群组设置不同的系统提示词
  • 使用 agentId 指定不同的 Agent（需先在 agents.list 配置）
  • 使用 Forum Topics 实现更细粒度的 Agent 区分

坑 7：插件配置格式

问题： 插件文档说用 plugins.allow，但配置文件里是 plugins.entries。

解决： 两种格式都可以：

  • plugins.allow - 旧版兼容格式
  • plugins.entries - 新版推荐格式

坑 8：代理配置位置

问题： OpenClaw 网关代理不是在配置文件里设置的。

解决： 通过环境变量设置（HTTP_PROXY、HTTPS_PROXY），不是 openclaw.json。

常用命令

配置相关

bash 复制代码 
# 查看配置
cat ~/.openclaw/openclaw.json

# 编辑配置
nano ~/.openclaw/openclaw.json

# 查看日志
openclaw logs --follow
tail -f /tmp/openclaw/openclaw-*.log

网关相关

bash 复制代码 
# 状态
openclaw gateway status

# 重启
openclaw gateway restart

配对相关

bash 复制代码 
# 查看待配对设备
openclaw pairing list telegram

# 批准配对
openclaw pairing approve telegram <CODE>

群组 ID 获取

bash 复制代码 
# 通过日志获取
openclaw logs --follow | grep chat.id

# 通过 Bot API 获取
curl "https://api.telegram.org/bot<token>/getUpdates"

模型切换

bash 复制代码 
# 查看当前模型
/session_status

# 切换模型（如果支持）
/model <model-name>

故障排查

1. 网关无法启动

bash 复制代码 
# 检查端口占用
lsof -i :18789

# 查看详细错误
openclaw gateway status
journalctl -u openclaw-gateway.service -n 100

2. Discord 机器人不在线

bash 复制代码 
# 检查日志
tail -100 /tmp/openclaw/openclaw-*.log | grep -i discord

# 确认配置
cat ~/.openclaw/openclaw.json | grep -A 10 '"discord"'

3. Telegram 群组不响应

bash 复制代码 
# 检查群组配置
cat ~/.openclaw/openclaw.json | grep -A 20 '"telegram"'

# 获取群组 ID
openclaw logs --follow | grep chat.id

4. 机器人不响应非 @ 消息

检查：

  1. BotFather: /setprivacy → Disable
  2. 配置 requireMention: false
  3. 重新添加机器人到群组

5. 代理不生效

bash 复制代码 
# 检查网关进程的环境变量
cat /proc/$(pgrep -f "openclaw-gateway")/environ | tr '\0' '\n' | grep -i proxy

# 重启服务（如果修改了 systemd）
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

更新日志

  • 2026-04-02 07:35：初始创建

    • 包含基础配置、渠道配置、踩坑记录

  • 2026-04-02 07:37：首次更新

    • 添加 Telegram 多群组独立 Agent 配置方案（3 种方式）
    • 添加 Forum Topics 支持说明
    • 添加群组 ID 获取方法
    • 添加常见问题（This group is not allowed、隐私模式）

  • 2026-04-02 15:40：内容补充

    • 添加 Gateway 绑定模式说明（auto、lan、tailnet、custom）
    • 添加 DingTalk 钉钉插件配置
    • 添加代理配置（环境变量方式）
    • 添加定时任务（OpenClaw cron vs 系统 cron）
    • 添加模型配置（OpenRouter、MiMo 免费试用提醒）
    • 补充踩坑记录（插件配置、代理配置位置）

相关链接

加载评论中...