OpenClaw 新手指南：本地 AI 自動化怎么跑起來

什么是 OpenClaw？

OpenClaw 是一個開源的、可本地運行的 AI 自動化框架。它不依賴云服務(wù)，所有數(shù)據(jù)和推理都在你自己的機器上完成。支持 WhatsApp、Telegram、Discord、Slack、Facebook Messenger 等 30+ 平臺，能統(tǒng)一配置、多端同步執(zhí)行任務(wù)。

它不綁定特定模型：Claude、GPT-3.5/4（通過 API）、Ollama 托管的本地模型（如 Llama 3、Qwen2）、甚至 Hugging Face 上的 Transformers 模型都能接入。調(diào)度邏輯寫在 YAML 里，模型切換只需改幾行配置。

本地化部署

沒有后臺服務(wù)，沒有數(shù)據(jù)上傳。消息解析、意圖識別、回復生成全部在本地完成。你控制輸入，也控制輸出——不需要為隱私或延遲妥協(xié)。

跨平臺任務(wù)編排

你寫一個任務(wù)，它就能在多個平臺生效。比如：

• 同一套規(guī)則，在 Telegram 和 WhatsApp 上同時監(jiān)聽關(guān)鍵詞
• 同一個工作流，把 Discord 的通知轉(zhuǎn)發(fā)到 Slack，并用本地模型摘要內(nèi)容
• 不用為每個平臺重寫邏輯，只維護一份 tasks/ 下的 YAML

多模型調(diào)度

OpenClaw 把模型當“插件”用。你在 config.yaml 里聲明可用模型，任務(wù)里指定用哪個：

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

任務(wù)中可以硬編碼模型名，也可以用條件路由（比如短文本走本地小模型，長文檔走 GPT-4o）。

安裝與配置

1. 基礎(chǔ)環(huán)境

確保系統(tǒng)滿足：

• Python 3.8+（3.7 已棄用，部分依賴不兼容）
• Git（用于拉代碼）
• 操作系統(tǒng)：Linux/macOS 推薦；Windows 需啟用 WSL2 或用 Conda 環(huán)境（PowerShell 原生命令支持有限）

?? 注意：OpenClaw 本身不帶大模型。調(diào)用本地模型需提前安裝 Ollama 或 vLLM；調(diào)用 API 模型需準備對應(yīng)密鑰。

2. 克隆代碼

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

別用 ZIP 下載——后續(xù)更新、切分支、提 PR 都會卡住。

3. 安裝依賴

pip install -r requirements.txt

依賴包含：

• httpx（異步 HTTP 客戶端，對接各平臺 Webhook）
• pyyaml（讀取配置和任務(wù)定義）
• jinja2（模板渲染，用于動態(tài)回復）
• 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 創(chuàng)建 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

服務(wù)默認監(jiān)聽 localhost:8000，Webhook 地址需反向代理（如 Nginx）暴露到公網(wǎng)。

寫第一個任務(wù)

在 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（或發(fā) SIGUSR1 信號熱重載，見 docs/hot-reload.md）。

驗證是否跑通

1. 查看終端日志：啟動無報錯，且顯示 Loaded X tasks
2. 在 Telegram 私聊你的 bot，發(fā) hello
3. 等待 1–3 秒（取決于本地模型加載速度），收到回復
4. 同樣測試 WhatsApp（需先完成 Meta 認證流程）

如果沒響應(yīng)：

• 檢查平臺 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 環(huán)境執(zhí)行（which python 和 which pip 是否一致）
• 報 ConnectionRefusedError：檢查 config.yaml 中 webhook_url 是否可訪問（本地測試用 ngrok http 8000 臨時暴露）
• 報 ValidationError：YAML 縮進錯誤，用 YAML Lint 校驗

自動回復不觸發(fā)

• 觸發(fā)詞被平臺過濾（如 WhatsApp 對短消息限頻），換長一點的 pattern："how are you doing today"
• Telegram Bot 設(shè)置了 Privacy Mode（默認開啟），需在 @BotFather 發(fā) /setprivacy → Disable
• 任務(wù)文件沒放在 tasks/ 目錄下，或擴展名不是 .yaml

模型返回空或超時

• Ollama 模型未拉?。?code>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 改成調(diào)用 action: "run_script"，執(zhí)行 Python 腳本查天氣、讀 RSS、寫數(shù)據(jù)庫
• 用 trigger.type: "schedule" 寫定時任務(wù)，比如每天早 8 點推送新聞?wù)?/li>
• 在 models.available 加入 transformers:bert-base-chinese，做中文情感分析再路由
• 看 examples/ 目錄里的真實用例：多輪對話狀態(tài)機、跨平臺客服工單同步、自動歸檔 Discord 日志

GitHub 倉庫：https://github.com/yourusername/OpenClaw
最新文檔：docs/ 目錄下的 Markdown 文件（比本指南更細）