OpenClaw 是一个开源 AI 助手框架，让你可以在多个消息平台（WhatsApp、Telegram、Discord 等）部署自己的 AI 助手。
Moltbook 是一个社区驱动的共享服务，OpenClaw 用户可以加入现有实例而无需自己托管。
适合人群：开发者、技术爱好者、需要私有 AI 助手的团队、以及任何想要掌控自己 AI 交互的人。
OpenClaw & Moltbook FAQ
新手常见问题与排错指南：从安装、配置、接入渠道到安全注意事项，快速跑通第一个成功案例。
共 33 个问题
OpenClaw 快速开始
先跑通第一个成功案例
Desktop（图形界面）推荐给新手 - 提供可视化配置、实时日志和一键操作。
CLI 更适合：
• 服务器部署
• 自动化和脚本
• 资源受限的环境
• 偏好终端工作流的开发者
两个版本核心功能完全相同。
你的最小成功清单：
1. OpenClaw 安装并运行（健康状态检查通过）
2. 至少配置一个模型 API Key（OpenAI、Anthropic 等）
3. 连接一个消息渠道（建议新手先用 Telegram）
4. 发送测试消息并收到回复
使用 Desktop 版本通常只需 5-10 分钟。
必需：
• 至少一个 AI 模型 API Key（OpenAI、Anthropic、Google 等）
渠道接入（至少选一个）：
• WhatsApp：只需手机上安装了 WhatsApp
• Telegram：通过 @BotFather 创建机器人
• Discord：在 Discord 开发者门户创建应用
可选：
• 网络搜索 API Key（增强功能）
从一个渠道开始的好处：
• 专注把基础搞对
• 清楚理解消息流程
• 更容易调试问题
• 先建立信心，再增加复杂度
熟悉之后，添加更多渠道会很简单。
OpenClaw 安装
安装与环境问题
安装后检查以下内容：
1. 运行 `openclaw health` 或 `openclaw status`（CLI）或在 Desktop 中查看健康状态
2. 确认所有服务都显示绿色对勾
3. 验证网关可访问（默认：http://127.0.0.1:18789）
4. 检查日志是否有错误信息
如果所有检查都通过，就可以配置渠道了。
启动问题 Top 5：
1. 端口被占用（其他应用在用 18789 端口）
2. API Key 缺失或无效
3. 权限不足（尝试以管理员身份运行）
4. 防火墙阻止连接
5. 依赖版本过旧（Node.js 需要 v22+）
先查日志 - 通常会指出具体问题。
解决方案：
1. 找到并停止冲突的进程：
• Mac/Linux: `lsof -i :18789` 然后 `kill [PID]`
• Windows (WSL): `lsof -i :18789` 然后 `kill [PID]`
2. 或者修改 OpenClaw 的端口：
• 启动时使用 `openclaw gateway --port 18790`
• 或在 onboard 时指定 `--gateway-port 18790`
按顺序尝试以下步骤：
1. 检查日志：`openclaw logs --follow` 查看错误信息
2. 重新配置：运行 `openclaw configure` 重新设置
3. 重新安装：`npm install -g openclaw@latest`
4. 查看发布说明中的破坏性变更
5. 如果仍然失败，带上日志到 GitHub Issues 报告
OpenClaw 主要通过 `~/.openclaw/openclaw.json` 配置文件管理设置。
常见问题：
1. 修改配置后没有重启服务
2. 使用了错误的配置路径
3. JSON 语法错误（缺少逗号、引号等）
4. 环境变量需要在 onboard 时通过参数传入
验证当前配置：运行 `openclaw status` 查看生效的设置。
OpenClaw 配置
设置与配置基础
用餐厅来类比：
• 模型 = 厨师（生成回复的 AI）
• 通道 = 入口（WhatsApp、Telegram 等）
• 网关 = 前台（接收和路由请求）
• 技能 = 特殊能力（网络搜索、代码执行等）
你至少需要一个模型和一个通道。网关自动运行。技能是可选的增强功能。
最简单的方式是运行交互式配置向导：
```
$ openclaw onboard
```
向导会引导你完成：
• 选择 AI 模型提供商（Anthropic/OpenAI 等）
• 输入 API Key
• 安装并启动网关服务
配置完成后，再用 `openclaw channels login telegram` 连接渠道。
默认网关绑定到 127.0.0.1:18789（仅本地访问，安全）。
在 Desktop 中：设置 → 技能 → 开关切换
在 CLI 中：
• 查看可用技能：`openclaw skills list`
• 安装技能：`openclaw skills install [skill-name]`
• 启用技能：`openclaw skills enable [skill-name]`
安全提示：
• 禁用不需要的技能
• 启用前先了解技能需要的权限
• 先在安全环境中测试新技能
• 有些技能可以执行代码 - 谨慎启用
切换模型：
1. 运行 `openclaw onboard` 重新配置，选择新的模型提供商
2. 或编辑 `~/.openclaw/openclaw.json` 中的 agents.defaults.model 设置
3. 重启服务：`openclaw gateway status` 确认运行状态
如果新模型失败：
• 运行 `openclaw models status` 检查模型连接状态
• 在提供商网站上检查 API Key 是否有效
• 验证模型名称拼写（如 `anthropic/claude-opus-4-5`）
• 检查账户的速率限制或配额
安全检查清单：
✓ 网关默认绑定到 localhost（127.0.0.1）
✓ 不要直接把端口暴露到公网
✓ 如果需要远程访问，使用：
• VPN 或 SSH 隧道
• 带认证的反向代理
• Cloudflare Tunnel
✓ 如果支持的话启用认证
✓ 生产环境使用 HTTPS
OpenClaw 渠道接入
各渠道特定问题
尝试以下修复：
1. 确保手机和电脑在同一网络
2. 刷新二维码（它们很快过期）
3. 更新手机上的 WhatsApp 到最新版本
4. 如果用网页界面，清除浏览器缓存
5. 在光线充足的环境扫码
6. 暂时关闭 VPN
如果仍然失败，试试手机链接码方式。
会话问题通常由以下原因导致：
1. 手机离线或休眠
2. 手机上的 WhatsApp 被登出
3. 在其他设备上使用了 WhatsApp Web
4. 网络不稳定
解决方法：
• 保持手机连接稳定的 WiFi
• 关闭 WhatsApp 的电池优化
• 不要在其他地方打开 WhatsApp Web
• 检查 WhatsApp 应用更新
群聊行为通常是有意设计的：
• 检查配置中是否启用了群聊回复
• 机器人可能需要 @提及才会在群里回复
• 出于安全考虑，默认配置可能禁用群消息
启用方法：
• 在 Desktop 设置中启用群聊回复
• 或通过 `openclaw pairing` 管理群聊权限
• 先在小群测试确保正常工作
Telegram 机器人默认启用隐私模式：
1. 打开 @BotFather
2. 发送 /mybots
3. 选择你的机器人
4. Bot Settings → Group Privacy → Turn OFF
或者，把机器人设为群管理员 - 管理员无论隐私模式如何都能看到所有消息。
简单步骤：
1. 打开 Telegram，搜索 @BotFather
2. 发送 /newbot
3. 选择一个名称（显示名）
4. 选择一个用户名（必须以 'bot' 结尾）
5. 复制提供的 API Token
6. 将 Token 添加到 OpenClaw 配置中
可选：使用 /setcommands 添加命令提示。
通常是 intents 问题：
1. 前往 Discord 开发者门户
2. 选择你的应用 → Bot
3. 启用这些特权 Intents：
• MESSAGE CONTENT INTENT
• SERVER MEMBERS INTENT（如果需要）
4. 保存并重启机器人
另外检查：机器人在频道是否有读取消息权限。
必需的 intents：
• Guilds - 基本服务器信息
• Guild Messages - 接收消息
• Message Content - 读取消息内容（特权）
可选：
• Guild Members - 用户信息（特权）
• Direct Messages - 私信支持
注意：特权 intents 在 100+ 服务器的机器人需要验证。
最小 Bot Token Scopes：
• chat:write - 发送消息
• app_mentions:read - 响应 @提及
• channels:history - 读取频道消息
• im:history - 读取私信
事件订阅：
• message.channels
• message.im
• app_mention
从最小权限开始，按需添加更多。
OpenClaw 故障排除
常见问题快速修复
401 表示认证失败。检查：
1. API Key 是否正确（没有多余空格）
2. Key 是否过期或被撤销
3. Key 是否有所需的权限/范围
4. 是否触发了速率限制
5. 账户是否有足够的额度/配额
先直接用提供商的 API 测试你的 Key。
逐步诊断：
1. 直接测试模型（curl/Postman）- 如果慢，是模型问题
2. 检查你的网络速度和延迟
3. 试试不同的模型（GPT-3.5 比 GPT-4 快）
4. 查看提供商状态页面是否有故障
解决方法：
• 增加超时设置
• 对长回复使用流式响应
• 尝试其他模型提供商
在日志中查找这些模式：
• 'FATAL' 或 'PANIC' - 严重错误
• 'OOM' - 内存不足
• 'ECONNREFUSED' - 无法连接依赖
• 堆栈跟踪 - 代码错误
常见修复：
• 增加内存分配
• 修复配置错误
• 更新到最新版本
• 检查外部服务可用性
配置排查：
1. 重启服务了吗？（大多数改动需要重启网关）
2. JSON 文件语法正确吗？（检查逗号、引号）
3. 是正确的配置文件吗？（应该是 `~/.openclaw/openclaw.json`）
4. 网关在运行吗？（`openclaw gateway status`）
验证配置：
• `openclaw status` - 查看整体状态
• `openclaw models status` - 检查模型连接
• `openclaw health` - 健康检查
日志位置：
• Desktop：查看 → 日志（或设置 → 打开日志文件夹）
• CLI：`~/.openclaw/logs/` 或标准输出
• Docker：`docker logs [容器名]`
关键错误关键词：
• ERROR, FATAL, PANIC - 严重问题
• timeout, ETIMEDOUT - 连接问题
• 401, 403, 429 - 认证/速率限制问题
• ENOENT - 文件/路径缺失
报告中包含：
1. OpenClaw 版本（`openclaw --version`）
2. 操作系统和版本
3. 复现步骤
4. 预期 vs 实际行为
5. 相关日志（移除敏感信息！）
6. 配置片段（移除 API Key！）
提交地址：GitHub Issues 页面
安全问题：直接发邮件给安全联系人
OpenClaw 安全指南
安全最佳实践
公网暴露的风险：
• 任何人都可以向你的 AI 发送请求
• API Key 可能被提取
• 可能被滥用（垃圾信息、非法内容）
• 未授权使用导致费用暴涨
• 机器人行为的法律责任
安全的远程访问选项：
• VPN（推荐）
• SSH 隧道
• Cloudflare Tunnel
• 带认证的反向代理
安全检查清单：
1. 是否来自官方/验证过的来源？
2. 如果有源码，检查一下
3. 阅读其他用户的评论/问题
4. 了解它请求什么权限
5. 先在隔离环境中测试
危险信号：
• 请求不必要的权限
• 代码被混淆/压缩
• 没有源码可查
• 没有社区反馈
立即行动：
1. 现在就在提供商网站上撤销这个 Key
2. 生成新的 Key
3. 用新 Key 更新所有配置
4. 检查使用历史是否有未授权调用
5. 复盘是怎么泄露的（git 历史？公开仓库？）
预防措施：
• 永远不要把 Key 提交到 git
• 使用 .env 文件（加入 gitignore）
• 生产环境使用密钥管理工具
安全默认配置：
• 网关只绑定到 localhost（127.0.0.1）
• 技能默认禁用
• 群消息初始禁用
• 启用速率限制
• 启用日志记录（用于审计）
• 渠道机器人使用最小权限
记住：从严格开始，按需放宽。
还是卡住了？
没找到你要的答案？试试这些资源：