龍蝦新手指南：OpenClaw——國產(chǎn)輕量級AI智能體框架入門

技術(shù)本質(zhì)

RAG+Agent架構(gòu)

OpenClaw 用 RAG（檢索增強(qiáng)生成）補(bǔ)足大模型的知識盲區(qū)，用 Agent 拆解任務(wù)、調(diào)用工具、維護(hù)狀態(tài)。它不靠大模型硬記所有信息，而是實時從本地知識庫中檢索相關(guān)內(nèi)容，再讓模型基于檢索結(jié)果生成回答或執(zhí)行動作。

比如你問“上個月銷售會議紀(jì)要里提到的交付時間是哪天”，OpenClaw 會先在你提供的會議文檔中定位相關(guān)段落，再讓模型精準(zhǔn)提取日期，而不是憑空猜測。

本地化執(zhí)行能力

所有推理、檢索、工具調(diào)用都在本地完成。沒有請求發(fā)往云端，沒有上下文上傳到第三方服務(wù)。你的郵件內(nèi)容、日程細(xì)節(jié)、航班號、聊天記錄——全留在你自己的機(jī)器上。

無需外部 API 密鑰

OpenClaw 不依賴 OpenAI、Claude 或任何商業(yè)大模型 API。它默認(rèn)使用本地運(yùn)行的 Llama 3、Qwen2 等開源模型（通過 Ollama 或 llama.cpp），開箱即用。你不需要注冊賬號、申請密鑰、擔(dān)心額度耗盡或賬單突襲。

全鏈路可審計

每條用戶指令進(jìn)來后，OpenClaw 會記錄完整的執(zhí)行流水：原始輸入 → 檢索到的文檔片段 → Agent 決策步驟（比如“需要調(diào)用 send_email 工具”）→ 工具參數(shù) → 執(zhí)行結(jié)果 → 最終回復(fù)。日志存為結(jié)構(gòu)化 JSON，隨時可查。

適配主流 IM 協(xié)議

目前支持微信（通過 WeChatPYAPI）、Telegram（通過 python-telegram-bot）、以及命令行 CLI。你不用切出聊天界面，直接在微信對話框里說“把上周日報發(fā)給張三”，它就調(diào) SMTP 發(fā)出去；在 Telegram 里輸“查下今天北京飛上海的航班”，它就拉取航旅 API 返回結(jié)果。

安裝與配置

步驟一：環(huán)境準(zhǔn)備

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

• 操作系統(tǒng)：Windows 10/11（WSL2 推薦）、macOS（Intel/M1/M2/M3）、Linux（Ubuntu/Debian/CentOS）
• Python：3.9–3.12（推薦 3.11）
• Git：用于拉代碼
• （可選）Ollama：如果想跑本地大模型，curl -fsSL https://ollama.com/install.sh | sh

Ubuntu/Debian 上快速準(zhǔn)備：

sudo apt update && sudo apt install -y python3.11 python3.11-venv python3-pip git

macOS（用 Homebrew）：

brew install python@3.11 git

Windows 用戶建議用 WSL2，避免路徑和權(quán)限問題。

步驟二：安裝 OpenClaw

1. 克隆倉庫（注意：替換為實際倉庫地址，原文中的 yourusername 需修正）：

git clone https://github.com/OpenClaw-Org/OpenClaw.git
cd OpenClaw

2. 創(chuàng)建虛擬環(huán)境并安裝依賴：

python3.11 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# .venv\Scripts\activate  # Windows
pip install --upgrade pip
pip install -r requirements.txt

?? 如果 pip install 卡在 chroma-hnswlib 或 llama-cpp-python，加 --no-binary :all: 參數(shù)重試，或按 README 中的平臺編譯說明操作。

步驟三：配置 OpenClaw

1. 復(fù)制配置模板：

cp config.example.yml config.yml

2. 編輯 config.yml：

nano config.yml

關(guān)鍵字段說明：

• llm: 指定本地模型。例如：

  llm:
    type: ollama
    model: qwen2:7b
    base_url: http://localhost:11434

• tools: 啟用哪些功能。如需發(fā)郵件，填入 SMTP 憑據(jù)；如需日歷，填入 iCal URL 或 Google Calendar token。
• im: 選 wechat、telegram 或 cli。微信需先掃碼登錄，Telegram 需 Bot Token。

微信配置提示：首次運(yùn)行 python3 main.py 會彈出二維碼，用手機(jī)微信「掃一掃」登錄即可，后續(xù)自動復(fù)用 session。

使用指南

啟動 OpenClaw

python3 main.py

啟動后，你會看到類似這樣的日志：

[INFO] Loaded LLM: qwen2:7b (Ollama)
[INFO] Loaded tool: send_email
[INFO] Loaded tool: add_calendar_event
[INFO] IM backend: wechat — waiting for messages...

此時打開微信，找到已登錄的聯(lián)系人（或群），直接發(fā)送自然語言指令。

常見指令示例

• 發(fā)郵件
  發(fā)郵件給 lisa@example.com，主題：項目進(jìn)度同步，正文：附件是Q3交付計劃，請查收。
• 加日程
  明天下午2點和王工在會議室B開需求評審會，時長1小時
• 查航班
  查CA123今天從北京首都到上海虹橋的起飛時間
• 查文檔
  上季度OKR文檔里，市場部的O2是什么？

OpenClaw 會解析語義、調(diào)用對應(yīng)工具、返回結(jié)構(gòu)化結(jié)果（比如郵件發(fā)送成功 ?，日程已添加到日歷 ??），全部過程在聊天窗口內(nèi)閉環(huán)。

驗證執(zhí)行結(jié)果

• 郵件：檢查收件人郵箱是否收到
• 日程：打開你的日歷應(yīng)用查看新事件
• 航班：對比航旅網(wǎng)站或 App 的實時狀態(tài)
• 文檔檢索：看返回內(nèi)容是否來自你指定的知識庫文件（如 okr_q3.pdf）

所有工具調(diào)用日志都寫在 logs/ 目錄下，按日期分文件，格式清晰可讀。

常見問題

微信登錄失敗 / 消息不響應(yīng)

• 確認(rèn) config.yml 中 im.type: wechat，且未誤設(shè)為 telegram
• 檢查 logs/wechat.log 是否有 login failed 或 session expired
• 刪除 wechat_session.pkl 文件，重啟 main.py 重新掃碼
• WSL2 用戶需確保 X11 轉(zhuǎn)發(fā)開啟（或改用 cli 模式調(diào)試）

指令被忽略或答非所問

• 檢查 config.yml 中 tools 下對應(yīng)功能是否設(shè)為 enabled: true
• 查 logs/agent.log：看是否檢索到了相關(guān)知識片段。若 retrieved_chunks: []，說明知識庫沒加載或關(guān)鍵詞匹配失敗
• 嘗試更明確的指令，比如把“提醒我開會”改成“15分鐘后提醒我參加產(chǎn)品站會”

pip install 報錯 llama-cpp-python

• Ubuntu/Debian：先裝構(gòu)建依賴

  sudo apt install -y build-essential cmake libblas-dev liblapack-dev

• macOS：用 LLAMA_METAL=1 強(qiáng)制啟用 GPU 加速（M系列芯片）

  LLAMA_METAL=1 pip install llama-cpp-python --no-cache-dir

• Windows：優(yōu)先用預(yù)編譯 wheel（見 llama-cpp-python releases）

實際使用場景

場景一：郵件處理（微信 + SMTP）

把 Outlook/Thunderbird 郵箱接入 OpenClaw 后，你在微信里說“把銷售合同發(fā)給客戶李總”，它自動：

• 從本地 contracts/ 文件夾找出最新版 PDF
• 填寫收件人、主題、正文模板
• 調(diào)用 SMTP 發(fā)送，返回“已發(fā)送至 li@client.com ?”

全程不離開微信，不打開郵箱客戶端。

場景二：日程管理（Telegram + iCal）

你在 Telegram Bot 對話中輸入：“下周三上午10點和法務(wù)約線上合同審核，鏈接用Zoom”，OpenClaw 會：

• 創(chuàng)建 .ics 事件，含 Zoom 鏈接、提醒前15分鐘
• 寫入你指定的網(wǎng)絡(luò)日歷（如 Nextcloud CalDAV）
• 向你 Telegram 回復(fù)：“? 已添加：合同審核（2024-06-12 10:00）”

場景三：航班提醒（CLI + 航旅 API）

命令行模式下運(yùn)行：

echo "提醒我CA123航班起飛前2小時" | python3 main.py --im cli

它會：

• 調(diào)用航旅公開 API 查詢 CA123 當(dāng)日計劃
• 在本地啟動定時任務(wù)（APScheduler）
• 到點推送微信消息：“CA123 北京→上海，預(yù)計14:25起飛，還有2小時，請準(zhǔn)備值機(jī)”

下一步

• 把你的內(nèi)部文檔（PDF/PPT/Markdown）放進(jìn) knowledge/ 目錄，運(yùn)行 python3 ingest.py 構(gòu)建向量庫，讓 OpenClaw 真正懂你公司的業(yè)務(wù)術(shù)語
• 修改 tools/email_tool.py，對接企業(yè)郵箱（如 Exchange Web Services）
• 在 prompts/agent.jinja 里調(diào)整 Agent 的 system prompt，讓它更符合你的溝通風(fēng)格（比如要求所有回復(fù)帶 ?/??/? 狀態(tài)圖標(biāo)）

官方倉庫持續(xù)更新：https://github.com/OpenClaw-Org/OpenClaw
遇到問題，直接提 issue —— 維護(hù)者每天看。