龍蝦新手指南：OpenClaw入門教程

什么是“龍蝦”

“龍蝦”是 OpenClaw 的代號，一個(gè)開源的本地 AI 助手。它不依賴云端服務(wù)，所有推理和處理都在你自己的機(jī)器上完成。名字取自龍蝦——外殼堅(jiān)硬（強(qiáng)調(diào)本地安全）、鉗子靈活（支持多模態(tài)和插件擴(kuò)展）、能適應(yīng)不同環(huán)境（跨平臺：Linux/macOS/Windows）。

項(xiàng)目地址：https://github.com/yourusername/OpenClaw
（注：實(shí)際使用時(shí)請?zhí)鎿Q為真實(shí)倉庫地址）

安裝前確認(rèn)

• 系統(tǒng)：Linux（Ubuntu 20.04+）、macOS（12+）、Windows 10/11
• 內(nèi)存：最低 4GB，推薦 8GB+（尤其啟用大模型時(shí)）
• Python：3.8 或更高版本
• Git：用于拉取代碼

檢查命令：

python3 --version  # 應(yīng)輸出 3.8.x 或更新
git --version        # 應(yīng)輸出 2.20+

如果缺失，從 python.org 和 git-scm.com 下載安裝。

安裝 OpenClaw

克隆代碼并進(jìn)入目錄

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

創(chuàng)建并激活虛擬環(huán)境

python3 -m venv venv
# Linux/macOS：
source venv/bin/activate
# Windows：
venv\Scripts\activate

安裝依賴

pip install -r requirements.txt

如果報(bào)錯(cuò) torch 安裝失敗，先按 PyTorch 官網(wǎng)推薦方式安裝對應(yīng) CUDA 版本的 torch（或 CPU 版），再重試。

運(yùn)行配置腳本

python configure.py

它會(huì)提示你設(shè)置：

• 默認(rèn)模型路徑（可留空，用內(nèi)置小模型快速啟動(dòng)）
• 本地知識庫存儲位置
• 是否啟用多模態(tài)（需額外安裝 transformers + Pillow）
• API 密鑰（僅限需要鑒權(quán)時(shí)；本地使用可跳過）

啟動(dòng)服務(wù)

python start_server.py

默認(rèn)監(jiān)聽 http://localhost:5000。終端出現(xiàn) INFO: Started server 即表示就緒。

驗(yàn)證是否跑通：

curl http://localhost:5000/api/v1/ping
# 返回：{"status": "pong", "version": "0.3.1"}

常用功能實(shí)操

文檔摘要

傳入一段文本，返回精煉摘要：

import requests

data = {"text": """
OpenClaw 是一個(gè)離線優(yōu)先的 AI 助手框架。它支持文本理解、代碼補(bǔ)全、圖像描述等能力，
所有模型均可在消費(fèi)級顯卡或 CPU 上運(yùn)行。設(shè)計(jì)目標(biāo)是可控、可審計(jì)、不聯(lián)網(wǎng)。
"""}

res = requests.post("http://localhost:5000/api/v1/summarize", json=data)
print(res.json()["summary"])
# 輸出類似：OpenClaw 是離線優(yōu)先的 AI 助手框架，支持文本、代碼、圖像處理，可在消費(fèi)級硬件運(yùn)行。

代碼輔助

給一段不完整的函數(shù)，返回補(bǔ)全建議或優(yōu)化提示：

import requests

data = {
    "code": "def calculate_tax(amount, rate):\n    return",
    "language": "python"
}

res = requests.post("http://localhost:5000/api/v1/code_assist", json=data)
print(res.json()["suggestions"][0])
# 輸出類似：return amount * rate / 100

多模態(tài)指令（純文本場景）

即使沒圖像，也能處理帶上下文的自然語言指令：

import requests

data = {
    "input": "把下面這段 Markdown 轉(zhuǎn)成 HTML：<h1>Hello</h1>",
    "type": "text"
}

res = requests.post("http://localhost:5000/api/v1/multimodal", json=data)
print(res.json()["response"])
# 輸出：<h1>Hello</h1>

加載自定義插件

OpenClaw 的插件是標(biāo)準(zhǔn) Python 模塊，放在任意目錄下，通過 --plugins 參數(shù)加載。

寫一個(gè)簡單插件

創(chuàng)建文件 plugins/weather.py：

def get_weather(city="Beijing"):
    # 實(shí)際項(xiàng)目中可對接本地天氣 API 或 mock 數(shù)據(jù)
    return f"Weather in {city}: Sunny, 26°C"

啟動(dòng)時(shí)加載

python start_server.py --plugins plugins

插件函數(shù)會(huì)自動(dòng)注冊為 /api/v1/plugin/weather 端點(diǎn)，調(diào)用方式：

curl -X POST http://localhost:5000/api/v1/plugin/weather \
  -H "Content-Type: application/json" \
  -d '{"city": "Shanghai"}'

排查常見問題

下一步

• API 文檔在 http://localhost:5000/api/v1/docs（Swagger UI）
• 想換更大模型？把 models/ 目錄替換成 GGUF 格式的 Llama 3 或 Qwen2 量化模型，再在 configure.py 中指定路徑
• 想加圖像理解？安裝 pip install transformers Pillow，啟用 --multimodal 啟動(dòng)參數(shù)，并傳入 base64 編碼圖片

所有改動(dòng)都不需要重新編譯——OpenClaw 是純 Python 實(shí)現(xiàn)，改完即生效。