乐于分享
好东西不私藏
夜雨聆风 > > 办公文件 > OpenClaw 完整安装与配置指南

OpenClaw 完整安装与配置指南

当前时间： 2026-08-16 15:08:26 分类：办公文件 评论(0)
OpenClaw 完整安装与配置指南

面向技术人员的实用教程，涵盖从安装到实际应用场景的完整指南

项目简介

OpenClaw 是一个开源的自托管 AI Agent 网关（GitHub 360k+ Stars），由社区驱动开发。它将你常用的聊天应用（Telegram、WhatsApp、Discord 等 22+ 平台）连接到 AI 编码代理，让你随时随地通过消息控制 AI 助手。

核心特性：

  • 自托管：运行在你自己的硬件上，数据完全可控
  • 多渠道：一个 Gateway 进程同时服务多个消息平台
  • Agent 原生：为编码代理构建，支持工具使用、会话管理、记忆系统
  • 开源：MIT 许可证，社区驱动

环境要求

必需组件

组件
版本要求
说明
Node.js
24（推荐）或 22.14+ LTS
运行时环境
npm
9+
包管理器
API 密钥
-
AI 模型供应商（OpenAI、Anthropic 等）

操作系统支持

  • 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 配置（最快上手）

  1. 在 Telegram 中搜索 @BotFather，创建新机器人
  2. 获取 Bot Token
  3. 配置到 openclaw.json：
{
"channels": {
"telegram": {
"enabled": true,
"token": "123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11",
"allowFrom": ["your_user_id"]
}
}
}
  1. 重启 Gateway：openclaw restart

Discord 配置

  1. 在 Discord 开发者门户创建应用
  2. 创建 Bot 并获取 Token
  3. 生成邀请链接并添加到服务器
  4. 配置到 openclaw.json

WhatsApp 配置

  1. 启用 WhatsApp 频道：openclaw channel enable whatsapp
  2. 扫描二维码连接
  3. 配置允许的用户号码

其他平台支持

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"]
}
}
}

最佳实践

安全配置建议

  1. 限制访问：只允许特定用户 ID 或电话号码
  2. 启用审批：对敏感命令启用人工审批
  3. 定期更新：保持 OpenClaw 和依赖项最新
  4. 备份数据：定期备份 ~/.openclaw/ 目录

性能优化

  1. 选择合适的模型：根据任务复杂度选择模型
  2. 使用技能缓存：启用技能热重载减少启动时间
  3. 优化记忆系统：定期清理过期的短期记忆
  4. 监控资源使用：关注 Token 消耗和 API 调用频率

备份和恢复

# 备份配置
tar -czf openclaw-backup-$(date +%Y%m%d).tar.gz ~/.openclaw/

# 恢复配置
tar -xzf openclaw-backup-20260428.tar.gz -C ~/

总结

OpenClaw 是一个功能强大的自托管 AI Agent 网关，通过本文档，你已经学会了：

  1. ✅ 安装和配置 OpenClaw
  2. ✅ 集成多种消息平台
  3. ✅ 使用技能系统扩展功能
  4. ✅ 在实际场景中应用 AI 助手
  5. ✅ 掌握高级功能和最佳实践

下一步建议：

  • 探索 ClawHub 技能市场，安装适合你的技能
  • 配置多个消息平台，实现全渠道覆盖
  • 创建自定义技能，满足特定需求
  • 加入社区，分享你的使用经验

相关资源：

  • 官方文档：https://docs.openclaw.ai
  • GitHub 仓库：https://github.com/anthropics/openclaw
  • 技能市场：https://clawhub.com
  • 社区论坛：https://community.openclaw.ai

最后更新：2026 年 4 月 28 日