OpenClaw 新手指南

为什么用 OpenClaw？

OpenClaw 是一个开源 AI 自动化框架，能本地运行，也能跨平台编排任务。它支持 WhatsApp、Telegram、Discord 等 30+ 平台，不依赖单一服务。你用 Claude、GPT 或本地大模型（比如 Llama 3、Phi-3）都行，模型调用逻辑统一，切换成本低。

本地部署 = 数据不离手

所有消息解析、AI 推理、任务调度都在你自己的机器上完成。配置文件、聊天记录、API 密钥全存在本地，没有后台上传行为。适合处理敏感信息或离线场景。

跨平台不是拼凑，是统一抽象

每个平台在 OpenClaw 里都映射为一个 Platform 实例：Telegram 用 bot token 和 chat_id，WhatsApp 用 WhatsApp Business API 凭据，Discord 用 bot token 和 channel ID。任务脚本里调用 oc.send_message()，底层自动路由到对应平台，不用写三套发送逻辑。

模型即插即用，不绑定供应商

openclaw.models 提供标准接口：generate(prompt)、stream(prompt)、embed(text)。只要封装好 GPTModel、ClaudeModel 或 LlamaCppModel，任务脚本里换一行初始化代码就能切模型。本地模型走 llama.cpp 或 Ollama，云端模型走官方 SDK，OpenClaw 只管输入输出格式。

安装步骤

前提条件

• Windows / macOS / Linux
• Python 3.7+
• Git

安装流程

1. 确认 Python

python --version
# 输出应为 Python 3.7.x 或更高

没装？去 python.org/downloads 下载安装包，勾选 “Add Python to PATH”。

2. 确认 Git

git --version
# 输出应为 git version 2.30+

没装？去 git-scm.com/downloads 下载安装。

3. 克隆代码

git clone https://github.com/your-repo/OpenClaw.git

4. 安装依赖

cd OpenClaw
pip install -r requirements.txt

常见报错？试试：

• pip install --upgrade pip
• Windows 上如果提示 Microsoft Visual C++ 14.0 缺失，装 Build Tools for Visual Studio
• macOS 上如果 llama-cpp-python 编译失败，先 brew install llvm，再 export CC=/opt/homebrew/opt/llvm/bin/clang

5. 配置环境变量

# Linux/macOS
export OPENCLAW_API_KEY=sk-xxx
export OPENCLAW_TELEGRAM_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11

# Windows PowerShell
$env:OPENCLAW_API_KEY="sk-xxx"
$env:OPENCLAW_TELEGRAM_TOKEN="123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11"

密钥存 .env 文件也行（需 pip install python-dotenv），但环境变量更直接，启动时自动加载。

快速上手：发一条 Telegram 消息

1. 配置 Telegram

编辑 config.yaml：

telegram:
  token: "${OPENCLAW_TELEGRAM_TOKEN}"
  chat_id: "-1001234567890"

chat_id 获取方式：把 bot 加进群，访问 https://api.telegram.org/bot<TOKEN>/getUpdates，看返回 JSON 里的 message.chat.id。

2. 写个任务脚本

在 tasks/hello_world.py 里：

from openclaw import OpenClaw

def main():
    oc = OpenClaw()
    oc.send_message("Hello from OpenClaw 🐾")

if __name__ == "__main__":
    main()

3. 运行它

python tasks/hello_world.py

成功的话，目标 Telegram 群/私聊会收到消息。失败？看终端报错——通常是 config.yaml 字段名写错、环境变量没生效，或网络连不上 Telegram API。

4. 加入 AI 生成

改写 hello_world.py：

from openclaw import OpenClaw
from openclaw.models import GPTModel

def main():
    oc = OpenClaw()
    model = GPTModel(model="gpt-4o-mini")
    response = model.generate("用一句话解释 OpenClaw 的核心价值")
    oc.send_message(f"🤖 {response.strip()}")

if __name__ == "__main__":
    main()

注意：GPTModel 会自动读取 OPENCLAW_API_KEY；本地模型换成 LlamaCppModel(model_path="./models/phi-3-mini.Q4_K_M.gguf") 即可。

故障排查

消息没发出去？

• 检查 config.yaml 里 telegram.token 和 telegram.chat_id 是否正确（尤其注意 -100 开头的群 ID）
• 运行 python -c "import os; print(os.getenv('OPENCLAW_TELEGRAM_TOKEN'))" 确认环境变量已加载
• 手动 curl 测试 Telegram API：curl "https://api.telegram.org/bot${OPENCLAW_TELEGRAM_TOKEN}/getMe"

ModuleNotFoundError: No module named 'openclaw'

• 确保你在 OpenClaw/ 目录下运行命令
• 或者 pip install -e . 把项目安装为可编辑模式

本地模型加载慢或 OOM？

• LlamaCppModel 默认用 4-bit 量化，加参数 n_gpu_layers=1 让部分层跑 GPU（需 CUDA 支持）
• 内存不足时，加 n_ctx=2048 限制上下文长度

下一步

• 看 examples/ 目录：定时提醒、多平台转发、PDF 总结、RAG 检索都有现成脚本
• 改 config.yaml 加 WhatsApp 或 Discord，复用同一套任务逻辑
• 在 models/ 目录下注册新模型类，只要实现 generate() 方法就能接入

资源

• OpenClaw GitHub 仓库
• OpenClaw 文档
• Python 官网
• Git 官网