OpenClaw 新手指南：本地 AI 自动化怎么跑起来

什么是 OpenClaw？

OpenClaw 是一个开源的、可本地运行的 AI 自动化框架。它不依赖云服务，所有数据和推理都在你自己的机器上完成。支持 WhatsApp、Telegram、Discord、Slack、Facebook Messenger 等 30+ 平台，能统一配置、多端同步执行任务。

它不绑定特定模型：Claude、GPT-3.5/4（通过 API）、Ollama 托管的本地模型（如 Llama 3、Qwen2）、甚至 Hugging Face 上的 Transformers 模型都能接入。调度逻辑写在 YAML 里，模型切换只需改几行配置。

本地化部署

没有后台服务，没有数据上传。消息解析、意图识别、回复生成全部在本地完成。你控制输入，也控制输出——不需要为隐私或延迟妥协。

跨平台任务编排

你写一个任务，它就能在多个平台生效。比如：

• 同一套规则，在 Telegram 和 WhatsApp 上同时监听关键词
• 同一个工作流，把 Discord 的通知转发到 Slack，并用本地模型摘要内容
• 不用为每个平台重写逻辑，只维护一份 tasks/ 下的 YAML

多模型调度

OpenClaw 把模型当“插件”用。你在 config.yaml 里声明可用模型，任务里指定用哪个：

models:
  default: "ollama:qwen2:7b"
  available:
    - "ollama:llama3:8b"
    - "openai:gpt-4o"
    - "anthropic:claude-3-haiku-20240307"

任务中可以硬编码模型名，也可以用条件路由（比如短文本走本地小模型，长文档走 GPT-4o）。

安装与配置

1. 基础环境

确保系统满足：

• Python 3.8+（3.7 已弃用，部分依赖不兼容）
• Git（用于拉代码）
• 操作系统：Linux/macOS 推荐；Windows 需启用 WSL2 或用 Conda 环境（PowerShell 原生命令支持有限）

⚠️ 注意：OpenClaw 本身不带大模型。调用本地模型需提前安装 Ollama 或 vLLM；调用 API 模型需准备对应密钥。

2. 克隆代码

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

别用 ZIP 下载——后续更新、切分支、提 PR 都会卡住。

3. 安装依赖

pip install -r requirements.txt

依赖包含：

• httpx（异步 HTTP 客户端，对接各平台 Webhook）
• pyyaml（读取配置和任务定义）
• jinja2（模板渲染，用于动态回复）
• ollama（可选，仅当你用 Ollama 模型时需要）

4. 配置平台与模型

编辑 config/config.yaml：

platforms:
  telegram:
    token: "654321:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"
    webhook_url: "https://your-domain.com/webhook/telegram"
  whatsapp:
    phone_id: "1234567890"
    verify_token: "my-secret-token"
    access_token: "EAAG..."

models:
  default: "ollama:qwen2:7b"
  openai:
    api_key: "sk-..."
    base_url: "https://api.openai.com/v1"
  anthropic:
    api_key: "sk-ant-..."

• Telegram 需先在 @BotFather 创建 bot 获取 token
• WhatsApp 需 Meta Developer 账户 + Business Manager 配置
• 本地模型（如 ollama:qwen2:7b）要求已运行 ollama run qwen2:7b

5. 启动

python main.py

启动后你会看到类似输出：

✅ Loaded 2 platforms: telegram, whatsapp
✅ Loaded 3 models: ollama:qwen2:7b, openai:gpt-4o, anthropic:claude-3-haiku
🚀 Listening on http://localhost:8000

服务默认监听 localhost:8000，Webhook 地址需反向代理（如 Nginx）暴露到公网。

写第一个任务

在 tasks/auto_reply.yaml 里写：

name: "Hello 回复器"
platforms: [telegram, whatsapp]
trigger:
  type: "message"
  pattern: "^hello|hi|hey$"
  case_sensitive: false
action:
  type: "reply"
  text: "Hello! How can I assist you today?"
  model: "ollama:qwen2:7b"  # 显式指定模型

• pattern 是正则表达式，^hello|hi|hey$ 匹配独立单词
• model 字段可省略，默认用 config 中的 default
• 支持 Jinja2 模板：text: "Hi {{ user.name }}! Time is {{ now | datetime('%H:%M') }}"

保存后重启 main.py（或发 SIGUSR1 信号热重载，见 docs/hot-reload.md）。

验证是否跑通

1. 查看终端日志：启动无报错，且显示 Loaded X tasks
2. 在 Telegram 私聊你的 bot，发 hello
3. 等待 1–3 秒（取决于本地模型加载速度），收到回复
4. 同样测试 WhatsApp（需先完成 Meta 认证流程）

如果没响应：

• 检查平台 Webhook 是否成功注册（Telegram 用 getWebhookInfo，WhatsApp 查 Cloud API 日志）
• curl -X POST http://localhost:8000/debug/log 查最近 10 条处理记录
• 用 --log-level debug 启动看详细链路：python main.py --log-level debug

常见问题

OpenClaw 启动失败

• 报 ModuleNotFoundError：确认 pip install 在当前 Python 环境执行（which python 和 which pip 是否一致）
• 报 ConnectionRefusedError：检查 config.yaml 中 webhook_url 是否可访问（本地测试用 ngrok http 8000 临时暴露）
• 报 ValidationError：YAML 缩进错误，用 YAML Lint 校验

自动回复不触发

• 触发词被平台过滤（如 WhatsApp 对短消息限频），换长一点的 pattern："how are you doing today"
• Telegram Bot 设置了 Privacy Mode（默认开启），需在 @BotFather 发 /setprivacy → Disable
• 任务文件没放在 tasks/ 目录下，或扩展名不是 .yaml

模型返回空或超时

• Ollama 模型未拉取：ollama list 看是否在列表里，不在就 ollama pull qwen2:7b
• OpenAI 密钥无效：curl https://api.openai.com/v1/models -H "Authorization: Bearer sk-..." 测试
• 本地模型显存不足：启动时加 --num-gpu 0 强制 CPU 推理（慢但能跑）

下一步

• 把 auto_reply.yaml 改成调用 action: "run_script"，执行 Python 脚本查天气、读 RSS、写数据库
• 用 trigger.type: "schedule" 写定时任务，比如每天早 8 点推送新闻摘要
• 在 models.available 加入 transformers:bert-base-chinese，做中文情感分析再路由
• 看 examples/ 目录里的真实用例：多轮对话状态机、跨平台客服工单同步、自动归档 Discord 日志

GitHub 仓库：https://github.com/yourusername/OpenClaw
最新文档：docs/ 目录下的 Markdown 文件（比本指南更细）