龙虾新手指南：从零入门 OpenClaw 智能体生态

为什么选 OpenClaw？

它不卖云服务，不收订阅费，代码全开源，能跑在你自己的笔记本、树莓派甚至旧 Mac 上。支持 Claude、GPT、Ollama 本地模型，也能切到 Llama 3 或 Qwen 等开源权重——模型是你挑，不是它塞。

消息平台接入实打实：WhatsApp（通过 Termux 或 Webhook）、Telegram Bot API、Discord Gateway、Slack App、Line、飞书、钉钉……目前稳定支持 32 个入口，不是“计划支持”。

所有数据留在本地。聊天记录、任务日志、配置文件，全在你硬盘上。config.yaml 里没一行发出去，main.py 就不会连一次外网（除非你主动配了远程模型）。

GitHub 31 万 star 不是刷的——那是真实开发者每天在提 issue、写插件、修 WebSocket 心跳超时、调 Telegram webhook 路由。工程细节扎实：有重试机制、会话上下文隔离、多 bot 并行、失败任务自动归档。

如果你不想被厂商锁死，又需要今天写完脚本、明天就能用 WhatsApp 接客户询盘，OpenClaw 是少数几个真能落地的选择。

什么是 OpenClaw？

OpenClaw 是一个智能体运行时（agent runtime），不是低代码拖拽工具，也不是封装好的 SaaS。它提供：

• 统一的消息总线：把不同平台进来的消息转成标准结构体
• 模型抽象层：换模型只需改 config 里一行 model: claude-3-haiku，不用动业务逻辑
• 任务生命周期管理：启动、暂停、热重载脚本、按需加载插件
• 原生 Python API：所有能力都通过 from openclaw import * 暴露，不藏黑盒

举个实际例子：
你写一个函数，接收 Telegram 消息 → 提取订单号 → 查本地 SQLite 订单表 → 生成物流状态文本 → 发回 Telegram。整个链路里，OpenClaw 只管“怎么收”和“怎么发”，中间查库、拼文案、调本地 Ollama，全由你控制。

它不替你思考，只帮你把想法快速变成可运行的服务。

如何安装和配置 OpenClaw？

1. 准备工作

确认系统已装好：

• Python 3.8+（3.7 已弃用，部分 asyncio 特性不兼容）
• Git（用于拉代码）
• pip（随 Python 自带，无需单独装）

检查命令：

python --version  # 应输出 3.8.x 或更高
git --version
pip --version

没装？Python 去 python.org 下 macOS/Windows 安装包；Linux 用户用 apt install python3 git 或 brew install python git。

2. 克隆仓库

git clone https://github.com/openclaw/OpenClaw.git
cd OpenClaw

注意：官方仓库是 openclaw/OpenClaw，不是 yourusername。fork 后再 clone 也行，但首次建议直接克隆主仓，避免同步问题。

3. 安装依赖

pip install -r requirements.txt

requirements.txt 里包含核心依赖：httpx（异步 HTTP）、pydantic（配置校验）、watchfiles（热重载）、各平台 SDK（如 python-telegram-bot）。如果报错缺 wheel，先 pip install wheel 再重试。

4. 配置 API 密钥

编辑 config.yaml，填入你有的模型密钥：

api_keys:
  openai: sk-xxx  # OpenAI
  anthropic: sk-ant-api03-xxx  # Anthropic
  ollama: http://localhost:11434  # 本地 Ollama 地址（不用密钥）

⚠️ 别把 config.yaml 提交到 GitHub。加进 .gitignore：

config.yaml
*.log
__pycache__/

5. 启动 OpenClaw

python main.py

看到类似输出即成功：

[INFO] Loaded 3 platforms: telegram, discord, whatsapp_web
[INFO] Model provider 'openai' ready (gpt-4o-mini)
[INFO] Agent runtime started on http://localhost:8000

此时 OpenClaw 已监听平台事件，但还没定义任何任务——下一步才是让它干活。

如何使用 OpenClaw？

1. 连接平台

以 Telegram 为例，在 config.yaml 中添加：

telegram:
  token: 123456789:ABCdefGhIjKlmNoPqrStUvWxYz  # BotFather 给的 token
  chat_id: -1001234567890  # 群组 ID，私聊用用户 ID（正数）

WhatsApp 需要额外步骤：用 whatsapp-web.js 启动浏览器实例，或配 Twilio。详细见 docs/platforms/whatsapp.md。

2. 创建任务

新建 tasks/echo.py：

from openclaw import TelegramBot

def handle_message(message):
    return f"收到：{message.text[:50]}...（自动回复）"

bot = TelegramBot()
bot.on_message(handle_message)

OpenClaw 会自动扫描 tasks/ 目录下的 .py 文件，加载并注册 on_message 回调。不需要手动 bot.start() —— runtime 启动时自动接管。

3. 运行任务

保存文件后，OpenClaw 默认启用热重载。你改完 echo.py，几秒内新逻辑就生效。
想手动触发重载，发 /reload 给 Telegram Bot（需在 config 中开启 admin 权限）。

测试：给 Bot 发一条消息，应该立刻收到带“自动回复”的回执。

验证安装和配置

• 看日志：终端输出 Loaded X platforms 和 Model provider Y ready 表示基础通了
• 查连接：发 /status 给 Telegram Bot（或访问 http://localhost:8000/status），返回各平台在线状态
• 测闭环：发消息 → 看日志是否打印 Received message from @xxx → 看是否收到回复
• 断网测试：拔网线，用本地 Ollama 模型跑任务——依然能工作，证明没偷偷连云端

如果卡在某步，直接翻 logs/app.log，错误堆栈比文档更诚实。

常见问题

1. Telegram 收不到消息

• 检查 token 是否复制完整（末尾 = 别漏）
• 确认 Bot 在群组里有“管理员”权限（至少要“能发消息”）
• 运行 python -m openclaw.platforms.telegram test 手动验证 token

2. pip install 报编译错误（尤其 macOS M1/M2）

• 先 brew install libpq（PostgreSQL 依赖）
• 再 pip install --no-binary :all: psycopg2
• 或改用 pip install "psycopg2-binary>=2.9"

3. 任务脚本修改后不生效

• 确认文件放在 tasks/ 目录下（不是子目录）
• 检查文件名是否含非法字符（如空格、中文）
• 日志里搜 Reloaded task，没这行说明没被扫描到

下一步学习建议

• 读 examples/ 目录：里面有真实场景脚本——自动归档飞书审批、解析邮件附件、定时推送 RSS
• 改 config.yaml 的 model 字段：切到 ollama:llama3，对比响应速度和成本
• 加日志：在任务函数里写 logger.info("订单 %s 已处理", order_id)，日志自动归集到 logs/tasks.log
• 写插件：参考 plugins/ 结构，用 @plugin 装饰器注入自定义功能（比如对接 MySQL）
• 看 PR 记录：GitHub 上搜 label:good-first-issue，挑一个修——社区欢迎真实补丁，不是“Hello World”

文档地址：

• GitHub 仓库
• 中文快速上手
• docs/ 目录下全是离线可用的 Markdown，git pull 就能更新