悦书阁
liufei379
2026-03-25
目录

OpenClaw 配置详解与踩坑记录

# 前言

OpenClaw (opens new window) 是一个开源的 AI Agent 框架，支持多模型、多渠道接入。本文记录我在配置过程中遇到的问题及解决方案，希望对后来者有所帮助。

# 配置文件位置

OpenClaw 的主配置文件位于：

~/.openclaw/openclaw.json
1

# 完整配置示例

以下是我在生产环境中使用的配置（敏感信息已脱敏）：

{
  "meta": {
    "lastTouchedVersion": "2026.3.8",
    "lastTouchedAt": "2026-03-20T15:49:02.708Z"
  },
  "wizard": {
    "lastRunAt": "2026-03-20T15:27:15.202Z",
    "lastRunVersion": "2026.3.8",
    "lastRunCommand": "doctor",
    "lastRunMode": "local"
  },
  "auth": {
    "profiles": {}
  },
  "models": {
    "mode": "merge",
    "providers": {
      "tencent-coding-plan": {
        "baseUrl": "https://api.lkeap.cloud.tencent.com/coding/v3",
        "apiKey": "XXX",
        "api": "openai-completions",
        "models": [
          {
            "id": "minimax-m2.5",
            "name": "MiniMax-M2.5",
            "reasoning": false,
            "input": ["text"],
            "cost": {
              "input": 0,
              "output": 0,
              "cacheRead": 0,
              "cacheWrite": 0
            },
            "contextWindow": 196608,
            "maxTokens": 32768
          },
          {
            "id": "kimi-k2.5",
            "name": "Kimi-K2.5",
            "contextWindow": 262144,
            "maxTokens": 32768
          },
          {
            "id": "glm-5",
            "name": "GLM-5",
            "contextWindow": 202752,
            "maxTokens": 16384
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "model": {
        "primary": "tencent-coding-plan/glm-5"
      },
      "models": {
        "tencent-coding-plan/glm-5": {},
        "tencent-coding-plan/kimi-k2.5": {},
        "tencent-coding-plan/minimax-m2.5": {}
      },
      "workspace": "/root/.openclaw/moyin/workspace",
      "compaction": {
        "mode": "default"
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "default": true,
        "workspace": "/root/.openclaw/moyin/workspace",
        "subagents": {
          "allowAgents": ["moxi"]
        }
      },
      {
        "id": "moxi",
        "workspace": "/root/.openclaw/moxi/workspace"
      }
    ]
  },
  "tools": {
    "profile": "coding"
  },
  "bindings": [
    {
      "agentId": "main",
      "match": {
        "channel": "telegram",
        "accountId": "moyin_bot"
      }
    }
  ],
  "messages": {
    "ackReactionScope": "group-mentions"
  },
  "commands": {
    "native": "auto",
    "nativeSkills": "auto",
    "restart": true,
    "ownerDisplay": "raw"
  },
  "session": {
    "dmScope": "per-channel-peer"
  },
  "hooks": {
    "internal": {
      "enabled": true,
      "entries": {
        "session-memory": {
          "enabled": true
        }
      }
    }
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "disabled",
      "groupPolicy": "disabled",
      "accounts": {
        "moyin_bot": {
          "enabled": true,
          "botToken": "XXX",
          "dmPolicy": "allowlist",
          "allowFrom": [123456789],
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["-100XXXXXXXXXX"],
          "groups": {
            "-100XXXXXXXXXX": {
              "requireMention": true,
              "allowFrom": [123456789, 987654321]
            }
          },
          "streamMode": "partial"
        },
        "default": {
          "enabled": false,
          "dmPolicy": "disabled",
          "groupPolicy": "disabled"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "https://openclaw-server.xxxx.ts.net"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "XXX",
      "allowTailscale": true
    },
    "tailscale": {
      "mode": "serve",
      "resetOnExit": false
    },
    "nodes": {
      "denyCommands": [
        "camera.snap",
        "camera.clip",
        "screen.record",
        "contacts.add",
        "calendar.add",
        "reminders.add",
        "sms.send"
      ]
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187

# 踩坑记录

# 1. MiniMax-M2.5 返回重复消息

问题描述：使用 minimax-m2.5 模型时，偶尔会收到两条相同的回复消息。

原因分析：MiniMax API 在流式响应时可能存在双推问题，与 OpenClaw 的 streamMode 配置产生冲突。

解决方案：

{
  "channels": {
    "telegram": {
      "accounts": {
        "moyin_bot": {
          "streamMode": "partial"
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11

将 streamMode 设置为 partial 可以缓解部分问题。如果问题持续，可以考虑：

  • 切换到其他模型（如 glm-5 或 kimi-k2.5）
  • 关闭流式输出（设置为 false）

# 2. HEARTBEAT.md 心跳无法触发

问题描述：在 HEARTBEAT.md 中定义了心跳检查规则，但实际运行时提醒没有按时触发。

原因分析：OpenClaw 的心跳机制依赖于 Gateway 的轮询，但 Gateway 默认不会主动轮询。需要通过外部调度触发心跳检查。

解决方案：使用 Cron 定时任务替代纯心跳依赖。

# 添加 cron 任务，每30分钟触发一次心跳
*/30 * * * * curl -s http://localhost:18789/api/wake
1
2

或者使用 OpenClaw 内置的 cron 功能：

openclaw cron add --name "heartbeat-check" --schedule "*/30 * * * *" --payload "heartbeat"
1

推荐配置：对于关键提醒（如吃药、订水），建议使用独立的 cron 定时器，而非依赖心跳检查：

提醒类型 推荐方式 Cron 表达式
吃药提醒 独立 cron 45 9 * * *
天气提醒 独立 cron 0 22 * * *
订水提醒 独立 cron 0 9 * * 4

# 3. Tailscale 安全访问控制台

问题描述：OpenClaw Gateway 控制台默认只监听 loopback，外网无法访问。直接暴露端口存在安全风险。

解决方案：使用 Tailscale 构建安全通道。

# 步骤 1：安装 Tailscale

curl -fsSL https://tailscale.com/install.sh | sh
tailscale up
1
2

# 步骤 2：配置 Gateway

{
  "gateway": {
    "port": 18789,
    "bind": "loopback",
    "controlUi": {
      "allowedOrigins": [
        "https://openclaw-server.xxxx.ts.net"
      ]
    },
    "auth": {
      "mode": "token",
      "token": "XXX",
      "allowTailscale": true
    },
    "tailscale": {
      "mode": "serve",
      "resetOnExit": false
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 步骤 3：启用 Tailscale Serve

# Tailscale 会自动配置 HTTPS
tailscale serve https:18789 / http://127.0.0.1:18789
1
2

# 步骤 4：访问控制台

https://openclaw-server.xxxx.ts.net
1

安全优势：

  • 无需开放公网端口
  • 自动 HTTPS 加密
  • 仅 Tailscale 网络成员可访问
  • 支持 Token 二次验证

# 4. 模型切换与 API Key 管理

问题描述：硬编码 API Key 存在安全风险，且切换模型时需要频繁修改配置。

解决方案：使用环境变量管理敏感信息。

# /etc/environment 或 ~/.bashrc
export TENCENT_API_KEY="your-api-key-here"
export TELEGRAM_BOT_TOKEN="your-bot-token"
1
2
3

配置文件中引用：

{
  "models": {
    "providers": {
      "tencent-coding-plan": {
        "apiKey": "${TENCENT_API_KEY}"
      }
    }
  }
}
1
2
3
4
5
6
7
8
9

注意：OpenClaw 目前不直接支持环境变量插值，需要通过启动脚本处理：

#!/bin/bash
export TENCENT_API_KEY="xxx"
openclaw gateway start
1
2
3

# 5. Telegram Bot 权限控制

问题描述：Bot 默认会对所有消息响应，存在误触发风险。

解决方案：配置白名单机制。

{
  "channels": {
    "telegram": {
      "accounts": {
        "moyin_bot": {
          "dmPolicy": "allowlist",
          "allowFrom": [123456789],
          "groupPolicy": "disabled"
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

配置说明：

  • dmPolicy: "allowlist" - 仅允许白名单用户私聊
  • allowFrom - 白名单用户 ID 列表
  • groupPolicy: "disabled" - 禁用群聊响应

# 6. Telegram 群组配置（踩坑实录）

问题描述：需要 Bot 在 Telegram 群组中响应消息，但配置了多次都无法正常工作。

# 尝试过程

尝试 1：直接设置 groupPolicy: "allowlist"

{
  "groupPolicy": "allowlist"
}
1
2
3

结果：群组消息无响应。

尝试 2：添加 groupAllowFrom 指定群组 ID

{
  "groupPolicy": "allowlist",
  "groupAllowFrom": ["-1003803855180"]
}
1
2
3
4

结果：群组消息仍无响应，日志显示权限被拒绝。

尝试 3：在 groups 中配置群组规则

{
  "groups": {
    "-1003803855180": {
      "requireMention": true
    }
  }
}
1
2
3
4
5
6
7

结果：Bot 收到消息但不响应，可能是因为没有用户白名单。

# 最终解决方案

必须同时配置三个字段：groupPolicy、groupAllowFrom、groups，缺一不可：

{
  "channels": {
    "telegram": {
      "accounts": {
        "moyin_bot": {
          "dmPolicy": "allowlist",
          "allowFrom": [123456789],
          "groupPolicy": "allowlist",
          "groupAllowFrom": ["-1003803855180"],
          "groups": {
            "-1003803855180": {
              "requireMention": true,
              "allowFrom": [123456789, 987654321]
            }
          }
        }
      }
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

配置说明：

字段 作用
groupPolicy 群组策略，allowlist 表示仅响应白名单群组
groupAllowFrom 允许的群组 ID 列表（字符串格式，以 -100 开头）
groups.<groupId>.requireMention 是否需要 @Bot 才响应（推荐 true，避免干扰群聊）
groups.<groupId>.allowFrom 群内允许触发 Bot 的用户 ID 列表

获取群组 ID 的方法：

  1. 将 Bot 加入群组
  2. 在群组中发送消息
  3. 查看 Gateway 日志或调用 getUpdates API：
curl -s "https://api.telegram.org/bot<BOT_TOKEN>/getUpdates" | jq '.result[-1].message.chat.id'
1

注意事项：

  • 群组 ID 是字符串格式（如 "-1003803855180"），用户 ID 是数字格式
  • requireMention: true 时，用户必须 @Bot 才能触发响应
  • 群组白名单用户需要同时在 allowFrom（私聊白名单）和 groups.xxx.allowFrom（群内白名单）中配置

# 配置项详解

# models 模块

字段 说明
mode 模型合并模式，merge 表示与内置模型合并
providers 模型提供商配置
contextWindow 上下文窗口大小（token数）
maxTokens 最大输出 token 数

# agents 模块

字段 说明
defaults.model.primary 默认主模型
defaults.workspace 工作目录
list Agent 实例列表
subagents.allowAgents 允许调用的子 Agent

# gateway 模块

字段 说明
bind 监听地址，loopback 仅本地
auth.mode 认证模式，token 为令牌认证
tailscale.mode serve 表示启用 Tailscale 服务

# 常用命令

# 检查配置
openclaw doctor

# 启动 Gateway
openclaw gateway start

# 重启 Gateway
openclaw gateway restart

# 查看状态
openclaw status

# 查看 cron 任务
openclaw cron list
1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 参考资源

本文持续更新中，如有问题欢迎留言讨论。

#OpenClaw#AI助手#配置
上次更新: 2026/4/28 12:56:42
AI技术入门指南
OpenClaw 接入飞书流程

← OpenClaw 接入飞书流程→

最近更新
01
IKEv2 VPN 部署教程
04-28
02
OpenClaw 接入飞书流程
03-27
03
AI技术入门指南
03-25
更多文章>
Theme by Vdoing | Copyright © 2022-2026 Felix | 粤ICP备17101757号-1