🚀 龙虾新手指南

OpenClaw本地智能体框架入门指南：纯离线RAG+Agent任务自动化部署

发布时间：2026-04-18 分类：龙虾新手指南

摘要：OpenClaw 新手指南：本地化智能体框架入门什么是 OpenClaw？OpenClaw 是一个轻量级、纯本地运行的 AI 智能体框架，专注任务自动化。它不走聊天界面路线，而是把 RAG（检索增强生成）和 Agent 能力封装成可执行单元，在你自己的设备上直接干活——没有 API 密钥，不传数据到云端。核心特点：本地执行：所有模型推理、文档检索、动作调度都在本机完成零外部依赖：不调用 Op...

OpenClaw 新手指南：本地化智能体框架入门

什么是 OpenClaw？

OpenClaw 是一个轻量级、纯本地运行的 AI 智能体框架，专注任务自动化。它不走聊天界面路线，而是把 RAG（检索增强生成）和 Agent 能力封装成可执行单元，在你自己的设备上直接干活——没有 API 密钥，不传数据到云端。

核心特点：

本地执行：所有模型推理、文档检索、动作调度都在本机完成
零外部依赖：不调用 OpenAI、Claude 或任何第三方 API
操作可追溯：每一步指令、检索结果、函数调用都记录在日志里
消息平台即入口：原生支持 Telegram、WhatsApp 等，发条消息就能触发任务

OpenClaw 和传统 LLM 的区别

传统 LLM 聊天工具输出的是文本。你问“帮我删掉上周的垃圾邮件”，它可能回你一段解释，甚至写个伪代码——但不会真删。

OpenClaw 不生成解释，它执行命令：

/run email_clean → 连上你的邮箱 IMAP，扫描、过滤、标记、删除
/schedule "明天下午3点和张三开会" → 写入本地 iCalendar 文件或同步到系统日历
/checkin BA123 2024-06-15 → 自动提交值机请求，返回电子登机牌 PDF

指令发出，动作落地。没有歧义，不靠“理解”，靠明确的函数绑定和参数校验。

如何安装和配置 OpenClaw？

前提条件

系统：Windows 10+、macOS 10.14+、Ubuntu 18.04+（其他 Linux 发行版需自行验证 systemd/dbus 支持）
Python：3.7 及以上（推荐 3.9–3.11）
pip：随 Python 安装，确保可用

安装步骤

确认 Python 环境
终端中运行：
```
python --version
pip --version
```
若报错，请先安装 Python（官网下载），勾选 “Add Python to PATH”。
创建虚拟环境（强烈建议）
隔离依赖，避免冲突：
```
python -m venv openclaw_env
```
激活：
- Windows：
```
openclaw_env\Scripts\activate
```
- macOS/Linux：
```
source openclaw_env/bin/activate
```
安装 OpenClaw
```
pip install openclaw
```
它会自动拉取 llama-cpp-python、chromadb、python-telegram-bot 等必要组件（首次安装可能耗时 2–5 分钟，取决于网络和编译速度）。
验证安装
```
openclaw --version
```
输出类似 openclaw 0.4.2 即成功。

配置 OpenClaw

初始化配置
```
openclaw init
```
生成 ~/.openclaw/config.yaml（Linux/macOS）或 %USERPROFILE%\.openclaw\config.yaml（Windows）。
配置消息平台（以 Telegram 为例）
编辑 config.yaml，填入 Bot Token 和 Chat ID：
```
telegram:
  token: "123456789:ABCdefGhIjKlmNoPqRsTuVwXyZ"
  chat_id: "987654321"
```
获取方式：
- 在 Telegram 搜索 @BotFather，发送 /newbot 创建机器人，拿到 token
- 新建一个群组，把机器人加为管理员，发送任意消息，用 getUpdates API 查看 chat.id

配置任务（以邮箱清理为例）

在 config.yaml 中添加：

tasks:
  email_clean:
    type: "email"
    params:
      host: "imap.gmail.com"
      port: 993
      email: "you@gmail.com"
      password: "your-app-password"  # Gmail 需用应用专用密码
      rules:
        - delete_spam: true
        - mark_important: true
        - archive_after: 30  # 30 天前的非重要邮件归档

⚠️ 敏感字段（如密码）建议改用环境变量：

password: "${EMAIL_PASSWORD}"

启动前执行 export EMAIL_PASSWORD="xxx"（Linux/macOS）或 set EMAIL_PASSWORD=xxx（Windows）。

使用 OpenClaw 执行任务

启动服务

openclaw start

服务以后台进程运行。默认监听 Telegram 消息（若配置了多个平台，会同时启动对应监听器）。

发送指令

在 Telegram 私聊或群组中，向你的 Bot 发送：

/run email_clean

OpenClaw 解析指令，加载 email_clean 任务定义，连接邮箱服务器，执行规则链，全程不离开你的机器。

查看结果

执行完成后，Bot 会回复结构化结果：

✅ Email cleaning completed (2.4s)
• Deleted: 7 spam emails
• Marked important: 2
• Archived: 14 old messages
• Left in inbox: 21

日志同时写入 ~/.openclaw/logs/openclaw.log，含完整时间戳和错误堆栈。

验证安装和配置

检查进程是否存活

Linux/macOS：
```
pgrep -f "openclaw start"
```

Windows（PowerShell）：

Get-Process | Where-Object {$_.CommandLine -like "*openclaw start*"}

手动触发测试任务
在 config.yaml 中加一个最小化测试任务：
```
tasks:
  test:
    type: "shell"
    params:
      command: "echo 'OK from $(hostname)'"
```
然后发 /run test。收到回执即说明配置、权限、执行链全部通路。

常见问题

OpenClaw 启动失败

报 ModuleNotFoundError：确认虚拟环境已激活，且 pip list | grep openclaw 显示已安装
报 OSError: [Errno 98] Address already in use：端口被占，改 config.yaml 中 server.port
macOS 上 llama-cpp-python 编译失败：先 brew install llvm，再重装 pip install llama-cpp-python --force-reinstall --no-deps

Telegram 没反应

检查 config.yaml 中 token 是否多空格或少字符（Telegram token 固定格式：数字:字母）
确保 Bot 在目标 chat 中有 sendMessages 权限（群组需设为管理员）
运行 openclaw logs 实时查看连接状态（会显示 Connected to Telegram, polling...）

任务执行卡住或报错

邮箱任务失败：确认 IMAP 开启（Gmail 需开启“允许不够安全的应用”或使用应用密码；Outlook 需启用 IMAP）
日历任务无响应：检查 calendar 依赖是否安装（pip install icalendar），以及 .ics 文件路径是否可写
所有任务超时：在 config.yaml 中调大 timeout 字段（单位秒，默认 30）

下一步学习建议

直接读 ~/.openclaw/tasks/ 下的内置任务源码（Python），看 email.py、calendar.py 怎么调用底层库
用 openclaw task create myscript --type shell 快速注册自定义脚本任务
尝试替换嵌入模型：把 config.yaml 中 embedding.model 改成 nomic-ai/nomic-embed-text-v1.5（需 pip install sentence-transformers）
查看完整配置项：openclaw config show
文档与更新日志：https://openclaw.ai/docs

返回首页