夜雨聆风面向技术人员的实用教程，涵盖从安装到实际应用场景的完整指南
项目简介
OpenClaw 是一个开源的自托管 AI Agent 网关（GitHub 360k+ Stars），由社区驱动开发。它将你常用的聊天应用（Telegram、WhatsApp、Discord 等 22+ 平台）连接到 AI 编码代理，让你随时随地通过消息控制 AI 助手。
核心特性：
自托管：运行在你自己的硬件上，数据完全可控 多渠道：一个 Gateway 进程同时服务多个消息平台 Agent 原生：为编码代理构建，支持工具使用、会话管理、记忆系统 开源：MIT 许可证，社区驱动
环境要求
必需组件
操作系统支持
macOS：原生支持，推荐用于桌面环境 Linux：完整支持，推荐用于服务器部署 Windows：通过 WSL2 支持
硬件建议
最低配置：2 核 CPU，4GB 内存，10GB 存储 推荐配置：4 核 CPU，8GB 内存，SSD 存储 网络：需要稳定的互联网连接（用于 API 调用）
安装步骤
方式一：官方安装（推荐）
# 1. 安装 OpenClaw
npm install -g openclaw@latest
# 2. 运行引导向导并安装服务
openclaw onboard --install-daemon
# 3. 验证安装
openclaw --version
方式二：手动安装
# 1. 克隆仓库
git clone https://github.com/anthropics/openclaw.git
cd openclaw
# 2. 安装依赖
npm install
# 3. 构建项目
npm run build
# 4. 启动 Gateway
npm start
方式三：Docker 部署
# 1. 拉取镜像
docker pull openclaw/openclaw:latest
# 2. 运行容器
docker run -d \
--name openclaw \
-p 18789:18789 \
-v ~/.openclaw:/root/.openclaw \
openclaw/openclaw:latest
# 3. 查看日志
docker logs -f openclaw
验证安装
# 检查版本
openclaw --version
# 启动 Gateway
openclaw start
# 打开控制面板
openclaw dashboard
访问 http://127.0.0.1:18789/ 验证是否正常运行。
基础配置
配置目录结构
~/.openclaw/
├── openclaw.json # 主配置文件
├── SOUL.md # Agent 人格定义
├── MEMORY.md # 持久记忆文件
├── USER.md # 用户信息
├── AGENTS.md # 工作区指令
├── IDENTITY.md # Agent 身份定义
├── TOOLS.md # 工具定义
└── DREAMS.md # 梦境整合（后台记忆提升）
核心配置示例
创建 ~/.openclaw/openclaw.json：
{
"gateway": {
"port": 18789,
"host": "0.0.0.0"
},
"providers": {
"anthropic": {
"apiKey": "your-api-key-here"
}
},
"channels": {
"telegram": {
"enabled": true,
"token": "your-telegram-bot-token",
"allowFrom": ["your-telegram-user-id"]
},
"whatsapp": {
"enabled": true,
"allowFrom": ["+15555550123"]
}
}
}
人格定义示例
创建 ~/.openclaw/SOUL.md：
# My AI Assistant
## 基本信息
- 名称：Jarvis
- 性格：专业、友好、高效
- 语言：中文为主，英文辅助
## 行为准则
1. 始终保持专业和礼貌
2. 回答简洁明了，避免冗余
3. 主动提供相关建议
4. 保护用户隐私和数据安全
## 专长领域
- 软件开发和代码审查
- 项目管理和任务协调
- 技术文档编写
- 数据分析和报告生成
消息平台集成
Telegram 配置（最快上手）
在 Telegram 中搜索 @BotFather，创建新机器人 获取 Bot Token 配置到 openclaw.json：
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
"allowFrom": ["your_user_id"]
}
}
}
重启 Gateway： openclaw restart
Discord 配置
在 Discord 开发者门户创建应用 创建 Bot 并获取 Token 生成邀请链接并添加到服务器 配置到 openclaw.json
WhatsApp 配置
启用 WhatsApp 频道： openclaw channel enable whatsapp扫描二维码连接 配置允许的用户号码
其他平台支持
OpenClaw 支持 22+ 平台，包括：
内置：Telegram、Discord、Slack、Signal、iMessage 插件式：Microsoft Teams、LINE、Nostr、Twitch、Zalo 等
技能系统
ClawHub 技能市场
OpenClaw 拥有 ClawHub 技能市场，包含 52.7k 工具，覆盖各种使用场景。
# 浏览可用技能
openclaw skills list
# 安装技能
openclaw skills install @clawhub/email-manager
# 安装 Graphify 技能
pip install graphify && graphify install --platform claw
创建自定义技能
创建 ~/.openclaw/skills/my-skill/SKILL.md：
# My Custom Skill
## 描述
自定义技能，用于处理特定任务
## 使用方法
1. 触发词：`my-skill`
2. 参数：`$ARGUMENTS`
3. 输出：处理结果
## 示例
用户：my-skill 处理这个文件
Agent：正在处理文件...
实际使用场景示例
场景一：开发者工作流
场景描述：通过手机远程管理代码仓库
# 用户通过 Telegram 发送消息
用户：帮我检查 main 分支的最新提交，运行测试并创建 PR
# OpenClaw 自动执行以下流程：
# 1. 拉取最新代码
# 2. 运行测试套件
# 3. 分析代码质量
# 4. 生成测试报告
# 5. 创建 Pull Request
# 最终回复
Agent：已完成代码检查：
✅ 测试全部通过（127 个测试用例）
⚠️ 发现 2 个代码风格警告
📝 已创建 PR #127：「修复用户认证模块的边界条件」
🔗 查看：https://github.com/your-repo/pull/127
实际代码示例：
# OpenClaw 执行的命令序列
git pull origin main
npm test
npm run lint
git checkout -b fix/auth-boundary
# ... 修改代码 ...
git commit -m "fix: 修复用户认证模块的边界条件"
git push origin fix/auth-boundary
gh pr create --title "fix: 修复用户认证模块的边界条件" --body "..."
场景二：个人效率提升
场景描述：自动化邮件和日历管理
# 每日早间简报（通过 Cron 调度自动触发）
Agent：早上好！今日简报：
📧 收件箱：5 封新邮件（2 封重要）
📅 日程：3 个会议
1. 10:00 - 产品评审会（会议室 A）
2. 14:00 - 技术方案讨论（线上）
3. 16:00 - 周报总结（会议室 B）
🎯 今日重点：完成 API 文档更新
# 邮件处理示例
用户：帮我回复关于项目进度的邮件
Agent：找到相关邮件 3 封，已生成回复草稿：
---
主题：Re: 项目进度更新
Hi [同事姓名],
感谢询问。项目当前进度：
- 后端开发：85% 完成
- 前端开发：70% 完成
- 测试：按计划进行中
预计下周三完成所有功能开发，周五进入测试阶段。
如有问题请随时联系。
Best regards,
[你的姓名]
---
是否发送？[是/否/修改]
场景三：智能家居/IoT
场景描述：通过消息控制智能设备
# 设备控制
用户：打开客厅的空气净化器
Agent：正在连接 Winix 净化器...
✅ 已开启净化器
📊 当前空气质量：PM2.5 = 35（良好）
🔧 运行模式：自动
💡 空气质量指示灯：绿色
# 自动化规则设置
用户：设置规则，当 PM2.5 > 75 时自动开启净化器
Agent：已创建自动化规则：
📋 规则名称：空气质量自动调节
🔄 触发条件：PM2.5 > 75
⚡ 执行动作：开启净化器，模式设为高速
🔔 通知：发送 Telegram 消息
✅ 规则已激活
# 状态查询
用户：所有设备状态如何？
Agent：当前设备状态：
🏠 客厅
- 净化器：运行中（PM2.5: 35）
- 空调：关闭
- 灯光：开启（亮度 80%）
🛏️ 卧室
- 空调：开启（26°C）
- 灯光：关闭
场景四：内容创作
场景描述：社交媒体和博客内容管理
# 推文生成
用户：帮我写一篇关于 AI 发展的推文
Agent：已生成推文草稿：
---
🚀 AI 正在重塑我们的工作方式。从代码审查到邮件管理，从智能家居到内容创作，AI Agent 已经成为真正的数字助手。
关键洞察：
1. 自托管 = 数据可控
2. 多渠道 = 随时随地
3. Agent 原生 = 深度集成
#AI #Agent #Automation #FutureOfWork
---
字数：280（符合推特限制）
是否发布？[是/否/修改]
# 博客文章生成
用户：根据我的 Obsidian 笔记生成一篇关于微服务架构的博客
Agent：已分析您的笔记，生成博客初稿：
---
# 微服务架构实践指南
## 引言
基于您的项目经验，总结微服务架构的最佳实践...
## 核心内容
1. 服务拆分策略
2. 通信机制选择
3. 数据管理方案
4. 部署和监控
## 您的项目案例
- 服务 A：处理用户认证
- 服务 B：管理订单流程
- 服务 C：数据分析引擎
---
初稿已保存到：~/drafts/microservices-blog.md
需要进一步完善哪个部分？
高级功能
多 Agent 路由
OpenClaw 支持最多 5 层嵌套的子 Agent，每个 Agent 可以有独立的工作区、人格和模型配置。
{
"agents": {
"coder": {
"model": "claude-opus-4-6",
"skills": ["code-review", "testing"],
"workspace": "/path/to/project"
},
"writer": {
"model": "gpt-4o",
"skills": ["content-creation", "seo"],
"workspace": "/path/to/blog"
}
}
}
Cron 调度
{
"cron": [
{
"name": "每日简报",
"schedule": "0 9 * * *",
"task": "生成今日简报并发送到 Telegram"
},
{
"name": "代码备份",
"schedule": "0 2 * * *",
"task": "备份代码仓库并上传到云存储"
}
]
}
梦境记忆整合
OpenClaw 的 DREAMS.md 机制会在后台自动将短期记忆提升为长期记忆，让 AI 助手越用越懂你。
常见问题
安装失败排查
# 检查 Node.js 版本
node --version # 需要 24 或 22.14+
# 清除 npm 缓存
npm cache clean --force
# 重新安装
npm install -g openclaw@latest
# 查看详细日志
openclaw --verbose start
API 密钥配置问题
# 设置环境变量
export ANTHROPIC_API_KEY="your-key-here"
export OPENAI_API_KEY="your-key-here"
# 或在配置文件中设置
# ~/.openclaw/openclaw.json
消息平台连接问题
# 检查 Gateway 状态
openclaw status
# 查看日志
openclaw logs
# 重启 Gateway
openclaw restart
权限和安全配置
{
"security": {
"allowFrom": ["+15555550123"],
"requireMention": true,
"commandApproval": {
"enabled": true,
"whitelist": ["git", "npm", "docker"]
}
}
}
最佳实践
安全配置建议
限制访问：只允许特定用户 ID 或电话号码 启用审批：对敏感命令启用人工审批 定期更新：保持 OpenClaw 和依赖项最新 备份数据：定期备份 ~/.openclaw/目录
性能优化
选择合适的模型：根据任务复杂度选择模型 使用技能缓存：启用技能热重载减少启动时间 优化记忆系统：定期清理过期的短期记忆 监控资源使用：关注 Token 消耗和 API 调用频率
备份和恢复
# 备份配置
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/
# 恢复配置
tar -xzf openclaw-backup-20260428.tar.gz -C ~/
总结
OpenClaw 是一个功能强大的自托管 AI Agent 网关，通过本文档，你已经学会了：
✅ 安装和配置 OpenClaw ✅ 集成多种消息平台 ✅ 使用技能系统扩展功能 ✅ 在实际场景中应用 AI 助手 ✅ 掌握高级功能和最佳实践
下一步建议：
探索 ClawHub 技能市场，安装适合你的技能 配置多个消息平台，实现全渠道覆盖 创建自定义技能，满足特定需求 加入社区，分享你的使用经验
相关资源：
官方文档：https://docs.openclaw.ai GitHub 仓库：https://github.com/anthropics/openclaw 技能市场：https://clawhub.com 社区论坛：https://community.openclaw.ai
最后更新：2026 年 4 月 28 日
