# OpenClaw 使用指南：配置、技巧与踩坑记录 > 本文档持续更新，记录 OpenClaw 的使用配置、踩坑点和最佳实践。 --- ## 目录 - [安装与基础配置](#安装与基础配置) - [多 Agent 配置](#多-agent-配置) - [渠道配置](#渠道配置) - [Telegram](#telegram) - [Discord](#discord) - [DingTalk](#dingtalk) - [技能管理](#技能管理) - [代理配置](#代理配置) - [定时任务](#定时任务) - [模型配置](#模型配置) - [踩坑记录](#踩坑记录) - [常用命令](#常用命令) - [故障排查](#故障排查) --- ## 安装与基础配置 ### 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: "", 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: "", 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: "", 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: "", dmPolicy: "pairing", groupPolicy: "allowlist", groups: { "*": { requireMention: false, groupPolicy: "open" } } } } } ``` #### 群组访问控制 ```json5 { channels: { telegram: { enabled: true, botToken: "", 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/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: "", groupPolicy: "allowlist", guilds: { "": { requireMention: false, users: [""] } }, 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 ``` ### 创建自定义技能参考：`~/.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 等敏感信息明文写在文章里。 **解决：** 使用占位符 ``，不要写实际值。 --- ### 坑 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


```

### 群组 ID 获取

```bash
# 通过日志获取
openclaw logs --follow | grep chat.id

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

### 模型切换

```bash
# 查看当前模型
/session_status

# 切换模型（如果支持）
/model 
```

---

## 故障排查

### 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 免费试用提醒）
  - 补充踩坑记录（插件配置、代理配置位置）

---

## 相关链接

- OpenClaw 官方文档：https://docs.openclaw.ai
- Discord 频道配置：https://docs.openclaw.ai/channels/discord
- Telegram 频道配置：https://docs.openclaw.ai/channels/telegram

标签: 踩坑

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