开始之前：了解您正在构建的内容
大多数AI安装指南将软件视为黑盒：下载、安装、忘记。clawbot不同，因为您不是在安装应用程序——您是在建立基础设施。可以将其想象为设置自己的私人电子邮件服务器，但不是管理消息，而是编排一个能够真正控制您数字环境的AI。
本指南解释了每个步骤做什么以及为什么重要。理解架构使故障排除变得直观，定制变得简单。
30分钟后您将拥有什么
- 在您的设备上持续运行的Gateway服务，协调所有AI活动
- 连接到您选择的AI模型（Claude、GPT-4或免费的本地Ollama）
- 至少一个与您的AI链接的消息渠道（WhatsApp、Telegram等）
- 演示真正系统控制的功能自动化
- 了解如何扩展、定制和排除设置故障
先决条件：您真正需要什么
在下载任何内容之前，请验证您的系统是否满足这些要求。每个要求都有特定目的：
硬件要求
- 操作系统：macOS 11+、Linux（Ubuntu 20.04+、Debian 11+）或Windows 10+（带WSL2）
- 内存：至少2GB可用（推荐4GB以实现更流畅的操作）
- 磁盘空间：核心安装需要500MB，外加AI模型缓存空间
- 网络：稳定的互联网连接用于AI API调用（除非使用本地Ollama）
软件依赖
clawbot需要Node.js 22或更高版本。为什么是这个特定版本？较新的Node.js版本包含了clawbot实时通信所依赖的关键性能改进和安全补丁。安装程序通常会处理此问题，但手动安装需要预先安装。
AI模型访问（选择一个）
成本效益分析：您应该选择哪个AI模型？
选项1：Anthropic Claude（推荐给大多数用户）
- 成本：典型个人使用约每月20-40美元
- 优势：卓越的推理能力、强大的安全意识、长上下文窗口
- 获取API密钥：console.anthropic.com
选项2：OpenAI GPT-4
- 成本：约每月25-50美元，取决于使用模式
- 优势：广泛的知识库，擅长创意任务
- 获取API密钥：platform.openai.com
选项3：本地Ollama模型（完全免费）
- 成本：0美元（完全在您的硬件上运行）
- 优势：零持续成本、完全隐私、离线操作
- 劣势：响应较慢，需要更强大的硬件（推荐8GB+内存）
- 设置：ollama.ai
步骤1：下载适合您平台的正确软件包
clawbot分发特定于平台的安装程序，捆绑了所需的一切。为什么有多种格式？不同的操作系统处理后台服务的方式不同——安装程序会正确配置这些。
macOS安装
下载DMG安装程序以获得最简单的体验：
curl -fsSL https://github.com/steipete/clawbot/releases/download/v2026.1.23/clawbot-2026.1.23.dmg -o clawbot.dmg
或直接从GitHub Releases下载。
安装程序的功能：
- 将Gateway服务安装到
/Applications/clawbot.app - 在
~/.clawbot/创建配置目录 - 配置自动化功能的系统权限
- 可选择设置启动时自动启动（推荐）
Linux安装
通过npm（推荐）或Docker安装：
npm install -g clawbot@latest
然后初始化配置：
clawbot init
设置为systemd服务（可选但推荐）：
clawbot install-service
这确保clawbot在启动时自动启动，并在崩溃时重新启动。
Windows安装（WSL2）
Windows需要WSL2（Windows子系统for Linux）。如果未安装：
wsl --install
然后在WSL2 Ubuntu环境中按照Linux说明操作。
⚠️ Windows原生支持
原生Windows支持（不使用WSL2）是实验性的。WSL2提供了与Node.js系统集成和shell命令执行更好的兼容性。
Docker部署
用于跨平台兼容性或服务器部署：
docker pull ghcr.io/steipete/clawbot:latest
使用持久配置运行：
docker run -d \
--name clawbot \
-v ~/.clawbot:/root/.clawbot \
-p 18789:18789 \
ghcr.io/steipete/clawbot:latest
理解Docker标志：
-d：在后台运行容器（守护进程模式）-v ~/.clawbot:/root/.clawbot：在重启之间持久化配置-p 18789:18789：为本地客户端公开Gateway WebSocket端口
步骤2：安装并启动Gateway
Gateway是clawbot的核心——一个持久化服务，管理消息平台、AI模型和您的系统之间的所有通信。将其视为中枢神经系统：渠道将消息发送到Gateway，Gateway将它们路由到适当的AI模型，接收响应，然后将它们发送回来。
运行安装程序
macOS：打开下载的DMG并将clawbot拖到应用程序。启动它。
Linux/WSL：npm安装后，启动Gateway：
clawbot gateway start
验证它是否正在运行：
clawbot gateway status
您应该看到：Gateway is running on ws://127.0.0.1:18789
🔍 幕后发生的事情
Gateway在端口18789（可自定义）上创建WebSocket服务器。这个仅限本地的服务器接受来自以下的连接：
- 渠道插件（WhatsApp、Telegram等）转发用户消息
- 节点客户端（移动应用、Web界面）用于直接交互
- 扩展功能的技能和工具
除非您明确配置远程访问（在高级指南中介绍），否则所有通信都保留在您的机器上。
步骤3：连接您的AI大脑
Gateway运行后，它需要AI模型来生成响应。此步骤配置您将使用的模型以及验证API访问。
配置AI提供商
打开配置文件：
clawbot config edit
或手动编辑~/.clawbot/clawbot.json。添加您的API凭据：
{
"aiProviders": {
"anthropic": {
"apiKey": "sk-ant-your-api-key-here",
"model": "claude-3-5-sonnet-20250219",
"enabled": true
}
},
"defaultProvider": "anthropic"
}对于本地Ollama：
{
"aiProviders": {
"ollama": {
"baseURL": "http://localhost:11434",
"model": "llama3.1:8b",
"enabled": true
}
},
"defaultProvider": "ollama"
}安全最佳实践：API密钥管理
如果clawbot.json包含API密钥，请不要将其提交到版本控制。考虑为生产部署使用环境变量：
export ANTHROPIC_API_KEY="your-key-here"
如果存在环境变量，clawbot会自动从中读取。
步骤4：链接您的通信渠道
渠道是您与AI交互的方式——移动设备上的WhatsApp、桌面设备上的Telegram、团队协作的Discord。每个渠道独立连接到Gateway，clawbot在所有渠道之间维护统一的对话历史。
连接您的第一个渠道：WhatsApp示例
安装WhatsApp渠道插件：
clawbot channel add whatsapp
这将启动交互式设置：
- 您的终端中出现二维码
- 在手机上打开WhatsApp → 设置 → 已链接的设备 → 链接设备
- 扫描二维码
- clawbot确认连接并保存会话凭据
工作原理：clawbot使用WhatsApp Web协议（通过Baileys库）建立持久连接。您的手机仍然是"主要"设备；clawbot充当链接的辅助设备——就像浏览器中的WhatsApp Web一样。
⚠️ WhatsApp账户安全
WhatsApp的服务条款禁止使用机器人。虽然clawbot实现了速率限制和类人行为模式，但我们建议使用辅助电话号码而不是您的主要个人WhatsApp账户。考虑：
- 获取Google Voice或类似的虚拟号码
- 使用您不主动使用的旧SIM卡
- 尝试Telegram（官方支持机器人）
替代渠道
每个渠道都有独特的设置要求。热门选项：
Telegram（推荐给初学者）：
clawbot channel add telegram
按照提示使用您的电话号码进行身份验证。Telegram官方支持机器人，使其成为最安全的选择。
Discord（非常适合团队）：
clawbot channel add discord
需要在discord.com/developers创建Discord机器人应用程序。在提示时复制机器人令牌。
完整渠道文档：docs.clawd.bot/channels
步骤5：执行您的第一个自主任务
一切配置完成后，让我们验证clawbot能够真正控制您的系统——而不仅仅是响应文本。
测试系统集成
打开您连接的消息渠道（WhatsApp、Telegram等）并发送此消息：
"在我的文档文件夹中创建一个名为test.txt的文本文件，包含今天的日期和一句励志名言。"
应该发生什么：
- clawbot通过渠道接收您的消息
- Gateway将其路由到您配置的AI模型
- AI生成包括shell命令的响应计划
- clawbot执行：
echo "..." > ~/Documents/test.txt - 您收到确认："已创建test.txt，包含..."
- 检查您的文档文件夹——文件存在
🎉 您刚刚演示了真正的AI自动化
clawbot与ChatGPT或Siri的区别：它不仅仅告诉您如何创建文件——它实际上创建了它。这种能力扩展到：
- 管理您的日历并发送会议邀请
- 监控日志文件并提醒您错误
- 从API提取数据并生成报告
- 通过Home Assistant控制智能家居设备
- 运行开发工作流程（测试、构建、部署）
接下来构建什么
您的AI基础设施已经运行。以下是如何扩展其功能：
1. 从ClawdHub安装技能
技能是预构建的自动化模块。浏览市场：
clawbot skills browse
热门入门技能：
- google-calendar：自然语言日历管理
- home-assistant：智能家居控制集成
- github-assistant：仓库管理和PR审查
- daily-briefing：早晨日历、天气、新闻摘要
2. 创建自定义自动化
技能只是带有SKILL.md文件的文件夹。创建您自己的：
mkdir -p ~/.clawbot/skills/my-automation
echo "# My Custom Skill" > ~/.clawbot/skills/my-automation/SKILL.md
完整指南：docs.clawd.bot/skills/creating
3. 配置主动行为
与传统AI不同，clawbot可以主动联系。启用心跳监控：
clawbot config set heartbeat.enabled true
clawbot config set heartbeat.interval "every day at 8am"
现在clawbot将主动向您发送早晨简报，无需询问。
4. 部署到云端（可选）
在笔记本电脑上运行clawbot可以工作，但云部署确保24/7可用性。可用指南：
- DigitalOcean Droplets（每月6美元）
- AWS EC2免费套餐（12个月免费）
- Hetzner Cloud（每月4欧元）
- 家庭Raspberry Pi（一次性硬件成本）
常见问题和解决方案
Gateway无法启动
症状：Error: EADDRINUSE: address already in use
原因：另一个进程正在使用端口18789。
解决方案：查找并终止冲突进程：
lsof -ti:18789 | xargs kill -9
或在clawbot.json中配置clawbot使用不同的端口。
AI模型返回错误
症状："API authentication failed"或"Invalid model specified"
原因：配置中的API密钥或模型名称不正确。
解决方案：验证您的API密钥是否有效：
curl https://api.anthropic.com/v1/messages \
-H "x-api-key: YOUR_KEY" \
-H "anthropic-version: 2023-06-01"
在提供商文档（Anthropic、OpenAI）中检查模型名称。
WhatsApp频繁断开连接
症状：每隔几天需要重新进行二维码身份验证。
原因：会话凭据未正确持久化。
解决方案：确保~/.clawbot/channels/whatsapp/具有写入权限：
chmod 700 ~/.clawbot/channels/whatsapp/
还要验证您的手机保持连接到互联网——WhatsApp需要主设备在线。
您现在正在运行自己的AI基础设施
您构建的不仅仅是一个聊天机器人——它是一个个人自动化平台，将前沿AI模型的智能与本地系统控制的能力相结合。与限制AI能力的云服务不同，您的clawbot安装可以访问您的数字环境，就像您一样。
这种权力伴随着责任：clawbot可以执行您批准的任何命令。沙箱和权限系统可以防止意外损坏，但最终您是在授予AI有意义的控制权。从简单的自动化开始，了解如何做出决策，并在建立信任时逐步扩展功能。