OpenClaw 本地 AI 智能体部署与实战指南

OpenClaw 本地 AI 智能体部署与实战指南

OpenClaw 是一个开源、本地优先的 AI 执行网关，能够连接大模型并直接操作电脑系统。本文详细介绍了其核心架构、跨平台安装部署流程、基础功能演示以及计算机视觉和文档生成的实战案例。

一、OpenClaw 核心认知：它是什么，能做什么

1.1 OpenClaw 到底是什么？

简单说，OpenClaw 就是一个本地 AI 执行网关，由奥地利程序员 Peter Steinberger 开发（PSDFKit 创始人）。

它的工作方式可以类比为一个"数字员工"：

• 大脑：连接大语言模型（GPT-4、Claude、通义千问等），理解你的自然语言指令
• 手脚：直接操作你的电脑系统——读写文件、执行终端命令、控制浏览器、发送邮件
• 记忆：保存你的偏好设置、任务历史，越用越懂你

与传统聊天机器人的本质区别：

传统 AI 聊天机器人：你问什么，它答什么。对话结束，任务结束。

OpenClaw 智能体：你发出指令，它自主拆解任务、调用工具、循环执行，直到任务完成。

比如，你说"帮我整理昨天的工作报告"，OpenClaw 会：

1. 找到昨天的文档
2. 分析文档内容
3. 提取关键信息
4. 创建新文档并整理格式
5. 保存到指定位置

整个过程全自动，你只需要下达一次指令。

1.2 核心功能全景

OpenClaw 采用模块化架构，核心分为 5 大模块：

1.2.1 Gateway 核心层

这是 OpenClaw 的"调度中枢"，本地常驻进程（默认地址：ws://127.0.0.1:18789），负责：

• 会话管理与状态维护
• 消息路由与转发
• 工具编排与权限校验
• 本地数据存储

技术细节：Gateway 使用 WebSocket 连接，确保毫秒级消息响应。支持多个聊天平台同时接入，每个平台的会话独立管理，互不干扰。

1.2.2 Channel 交互层

这是 OpenClaw 的"感官系统"，对接各类通讯渠道，将你的指令输入、执行结果输出到熟悉的工作环境。

支持的核心平台：

• 即时通讯：WhatsApp、Telegram、Signal、iMessage
• 企业协作：Discord、Slack、飞书、钉钉
• 特殊场景：Google Chat、Microsoft Teams、WebChat

核心优势：你无需打开专用 App，就在日常使用的聊天软件中，通过发送消息的方式控制本地电脑。

1.2.3 LLM 决策层

这是 OpenClaw 的"大脑"，接入大模型能力，负责：

• 自然语言理解（NLU）
• 任务拆解与规划
• 工具调用决策
• 结果语义化整理

支持的模型：

• 云端模型：Anthropic Claude、OpenAI GPT、Google Gemini
• 本地模型：Ollama（支持 Llama、Qwen、Mistral 等）
• 国内模型：阿里云百炼（通义千问）、月之暗面（Kimi）、DeepSeek

模型切换策略：根据任务复杂度自动选择——简单任务用轻量模型（速度快），复杂任务用高性能模型（能力强）。

1.2.4 Tools 执行层

这是 OpenClaw 的"手脚"，系统操作执行单元，包含：

文件工具：

• 读取、写入、复制、移动、删除文件
• 批量重命名、格式转换
• 文件搜索与内容解析（支持 PDF、Word、Excel）

终端工具：

• 执行 Shell 命令（Bash、PowerShell、CMD）
• 进程管理（启动、停止、重启服务）
• 系统信息查询（CPU、内存、磁盘）

浏览器工具：

• 网页自动化操作（点击、填表、截图）
• 数据抓取与解析
• 支持 Chrome、Chromium、Playwright 引擎

定时任务：

• Cron 表达式支持
• 定期执行备份、数据同步等任务

1.2.5 Memory 记忆层

这是 OpenClaw 的"记忆系统"，分为三层：

• 短期记忆：当前会话的上下文（最近 10 轮对话）
• 长期记忆：用户偏好、重要事件（如"我经常用 Python 处理数据"）
• 向量检索：基于 Lancedb 的高性能向量库，支持语义搜索（如"我上周说过的那个文件"）

记忆管理策略：

记忆分层策略：会话级：自动压缩（~400 token/块，重叠 80 token）持久化：Markdown + 向量索引时间衰减：score = score × e^(-λ × age)

1.3 适用场景：谁最适合用 OpenClaw？

1.3.1 知识工作者（强烈推荐）

目标人群：分析师、研究员、内容创作者、管理者

核心痛点：

• 数据收集耗时：每天浏览 10+ 网站，手动复制粘贴整理
• 文档处理繁琐：每周整理报告、生成 PPT、发送邮件
• 信息检索困难：记得某个文件但找不到位置

OpenClaw 解决方案：

# 示例 1：一键整理竞品数据
"帮我从这 10 个网站抓取上周的产品更新信息，整理成 Excel 表格"

# 示例 2：自动生成周报
"读取各部门周报，整合成公司周报，提取关键数据，生成下周工作计划"

效率提升：

• 数据收集：从 2 小时降至 15 分钟
• 文档处理：从 1 小时降至 5 分钟
• 信息检索：秒级响应，无需手动翻找

1.3.2 开发者/工程师

目标人群：前端、后端、运维、算法工程师

核心痛点：

• 环境配置重复：每次新项目都要配置开发环境
• 代码整理耗时：手动重构、添加单元测试很慢
• 文档生成繁琐：API 文档、技术手册需要手动编写

OpenClaw 解决方案：

# 示例 1：自动配置开发环境
"帮我创建一个 React TypeScript 项目的标准目录结构，安装依赖，配置 ESLint 和 Prettier"

# 示例 2：自动生成 API 文档
"读取这个项目的代码注释，生成 Swagger 格式的 API 文档，包括所有端点和参数说明"

实际案例： 有开发者分享，用 OpenClaw 自动完成了：

• 将整个 React 代码库重构为 TypeScript
• 添加了错误边界和单元测试
• 完成了 K8s 集群部署（原来需要一周，现在 10 分钟）

1.3.3 自由职业者

目标人群：咨询师、设计师、独立开发者、文案

核心痛点：

• 多任务协调难：客户沟通、项目管理、发票处理并行进行
• 文档管理混乱：合同、发票、方案散落在各处
• 邮件处理量大：每天 50+ 封邮件，分类回复耗时

OpenClaw 解决方案：

# 示例 1：自动分类邮件
"自动分类所有邮件：客户咨询、供应商、团队汇报，用模板回复常见问题，提取待办事项"

# 示例 2：合同管理
"帮我扫描 Documents/Contracts 目录，识别即将到期的合同，按到期日期排序，生成续约提醒清单"

1.3.4 学生/研究者

目标人群：大学生、研究生、研究人员

核心痛点：

• 文献收集慢：手动下载 PDF、整理引用很耗时
• 笔记整理难：课堂笔记、论文笔记散落在各处
• 数据处理重复：每次实验都要重新清洗数据

OpenClaw 解决方案：

# 示例 1：文献管理
"从 arXiv 下载过去 30 天的 CVPR 论文，按主题分类，提取摘要生成综述，保存到 BibTeX"

# 示例 2：实验数据自动处理
"读取实验数据 CSV，检测异常值，生成可视化图表，计算统计指标，输出 LaTeX 格式表格"

1.4 核心优势：为什么选择 OpenClaw？

1.4.1 完全本地化，隐私安全

数据不出本地：

• 所有会话记录、执行日志、数据处理均在本地完成
• 无需上传到云端服务器
• 断网也能使用（连接本地模型时）

安全性对比：

方式	数据存储	隐私风险	离线可用
云端 AI（如 ChatGPT Web）	服务器端	高（无法控制）	否
OpenClaw（本地模式）	本地设备	低（完全可控）	是
OpenClaw（云端模式）	本地设备	中（密钥泄露风险）	否

1.4.2 真正执行任务，而非"纸上谈兵"

传统 AI vs OpenClaw：

传统 AI 聊天机器人：

• 用户："帮我整理文件"
• AI："好的，我可以帮你整理文件。你需要整理哪些文件？整理到什么位置？"
• 用户：（手动逐个描述）
• AI：（继续问，手动执行）
• 结果：对话结束，任务未完成

OpenClaw 智能体：

• 用户："帮我整理文件"
• AI：（自动执行）
  1. 识别"整理文件"意图
  2. 调用文件系统工具
  3. 扫描当前目录
  4. 按类型分类
  5. 移动文件到对应文件夹
• 结果：任务完成，返回执行结果

1.4.3 开源免费，无商业限制

• 完全免费使用
• 可用于商业项目
• 支持二次开发和定制
• 无使用人数限制

1.4.4 跨平台与多渠道集成

三大平台支持：

• macOS：完整支持，包括菜单栏 App
• Windows：原生 Windows 和 WSL2 支持
• Linux：Ubuntu、Debian、Arch 等主流发行版

20+ 通讯平台：从 WhatsApp 到钉钉，覆盖全球主流沟通工具。

二、环境准备：安装前必读

2.1 系统要求

最低配置要求：

项目	最低要求	推荐配置	说明
操作系统	Windows 10+（64 位）macOS 12+ Linux（Ubuntu 20.04+/Debian 11+）	Windows 11 / macOS 14+ / Ubuntu 22.04+	Windows 建议使用 WSL2 以获得更好的兼容性
运行环境	Node.js 22+	Node.js 22.x LTS	使用 nvm/nvm-windows 管理版本
内存（RAM）	2GB	4GB 及以上	本地运行模型建议 8GB+
硬盘空间	500MB	1GB 及以上	包含依赖、安装文件、缓存
网络	稳定连接	宽带/WiFi	调用云端 AI 需联网；本地模型可离线
可选依赖	-	Python 3.10+ Git	部分技能需要 Python；源码编译需要 Git

硬件兼容性表：

硬件类型	最低配置	推荐配置	适配模型
普通笔记本	i5/8GB/SSD 256GB	i7/16GB/SSD 512GB	Qwen3.5-2B/4B、Llama 3 8B
MacBook	M1/8GB	M2-M3/16GB+	Qwen3.5-4B/9B、Llama 3 70B
台式机	RTX 3060 12GB	RTX 4090 24GB / Mac Studio M3 Ultra	所有本地模型、多模态
服务器	4 核/16GB	8 核/32GB+	多实例部署、模型微调

2.2 安全考虑（非常重要）

警告：OpenClaw 具备系统级权限，需谨慎使用

OpenClaw 支持两种运行模式：No Risk（安全模式）：仅聊天能力，禁止文件操作、终端命令等敏感操作；Full Access（完整权限）：允许所有操作，包括读写文件、执行命令等。

推荐安全配置：

# ~/.openclaw/openclaw.json 安全配置示例
{
  "gateway": {
    "auth": {
      "mode": "token",
      "allowFrom": [
        "+1234567890",
        "192.168.1.100"
      ]
    }
  },
  "agents": {
    "defaults": {
      "permissions": {
        "allowFileSystem": true,
        "allowTerminal": true,
        "allowNetwork": false,
        "allowBrowser": true
      }
    }
  }
}

安全最佳实践：

1. 白名单机制：仅允许可信的联系人或 IP 地址发送指令
2. 网络访问控制：禁止网络访问（除非必要），防止恶意代码外泄数据
3. 定期审计日志：检查 ~/.openclaw/logs/ 目录，发现异常操作
4. 权限最小化原则：不常用的操作不授权，必要时临时开启 Full Access

2.3 核心提醒：90% 报错的根源

根据大量新手反馈，以下是最常见的安装失败原因：

2.3.1 权限不足（Windows 最常见）

症状：

Access denied / 拒绝访问 / permission denied

原因：Windows 未以管理员身份运行 PowerShell；安装路径包含中文字符、空格或特殊符号

解决方案：

# Windows PowerShell：右键选择"以管理员身份运行"
# 步骤：Win + R -> powershell -> 右键"Windows PowerShell" -> 以管理员身份运行

2.3.2 Node.js 版本过低

症状：

Error: Node.js version too old / 版本过低

原因：OpenClaw 要求 Node.js 22+，系统安装了旧版本

解决方案：

# 检查当前版本
node --version

# 使用 nvm 安装最新 LTS 版本（macOS/Linux）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22

# Windows 使用 nvm-windows
# 下载并安装 nvm-windows：https://github.com/coreybutler/nvm-windows/releases
nvm install 22
nvm use 22

2.3.3 端口被占用

症状：

EADDRINUSE: address already in use / 端口已被占用

原因：默认端口 18789 或 3000 被其他程序占用

解决方案：

# 方案 1：修改配置文件更换端口
# 编辑 ~/.openclaw/openclaw.json
{
  "gateway": {
    "port": 18790
  }
}

# 方案 2：找到并关闭占用端口的程序
# macOS/Linux
lsof -ti:18789 | xargs kill -9

# Windows PowerShell
Get-NetTCPConnection -LocalPort 18789 | Select-Object OwningProcess | Stop-Process -Force

2.3.4 下载速度慢

症状：依赖下载卡在某个百分比，迟迟不完成

原因：国外服务器访问慢

解决方案：

# 配置 npm 国内镜像
npm config set registry https://registry.npmmirror.com

# 配置 yarn 镜像
yarn config set registry https://registry.npmmirror.com

# 使用国内一键脚本（OpenClaw-CN）
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex
# macOS/Linux
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

三、安装部署：全平台保姆级教程

3.1 Windows 系统安装

3.1.1 方式一：一键脚本安装（新手首选，5 分钟搞定）

优点：全自动配置，适合零基础用户

步骤详解：

Step 1：以管理员身份打开 PowerShell

Step 2：执行一键安装命令 复制以下命令，完整粘贴到 PowerShell 窗口，按回车键执行：

# Windows 一键安装脚本（官方最新版）
iwr -useb https://openclaw.ai/install.ps1 | iex

国内网络优化（如果下载慢）：

# 使用 OpenClaw-CN 国内加速镜像
iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex

安装过程说明：

• 脚本会自动检测系统环境
• 自动安装 Node.js 22+（如果未安装）
• 下载 OpenClaw 核心程序
• 配置环境变量和路径
• 全程 3-8 分钟（取决于网速）

成功标志：终端出现：

✓ OpenClaw installed successfully ✓ Version: v2026.3.2

Step 3：验证安装

# 查看安装的版本号
openclaw --version

# 系统环境诊断
openclaw doctor

3.1.2 方式二：使用 WSL2（推荐，最稳定）

优点：在 Linux 子系统中运行，兼容性最佳，接近原生 Linux 体验

适用场景：需要开发环境稳定性；避免 Windows 文件系统权限问题

步骤详解：

Step 1：安装 WSL2

# 管理员 PowerShell 中执行
wsl --install

等待安装完成，系统提示重启。

Step 2：重启电脑 根据提示重启，WSL2 会自动安装 Ubuntu 子系统。

Step 3：进入 WSL2 环境 重启后，在开始菜单找到"Ubuntu"（或"WSL"），打开 Ubuntu 终端。

Step 4：在 WSL2 中安装 OpenClaw

# 在 Ubuntu 终端中执行（与 macOS/Linux 命令一致）
curl -fsSL https://openclaw.ai/install.sh | bash

优势：

• Linux 文件系统更稳定
• 包管理器（apt）更完善
• 开发工具链更齐全

3.1.3 方式三：包管理器安装（适合有基础用户）

前提：已手动安装 Node.js 22+

npm 安装：

# 安装最新版
npm install -g openclaw@latest

# 安装特定版本
npm install -g [email protected]

# 安装 Beta 版
npm install -g openclaw@beta

pnpm 安装（推荐，更快、省空间）：

# 先安装 pnpm（如果未安装）
npm install -g pnpm

# 使用 pnpm 安装 OpenClaw
pnpm add -g openclaw@latest

3.1.4 方式四：源码编译安装（适合开发者）

适用场景：需要自定义修改源码

前提：已安装 Git 和 pnpm

步骤：

# 1. 克隆源码
git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 2. 安装依赖并编译
pnpm install
pnpm run build

# 3. 启动配置向导
pnpm run openclaw onboard

3.2 macOS 系统安装

3.2.1 方式一：一键脚本安装（5 分钟搞定）

Step 1：打开终端 按 Command + 空格，打开聚焦搜索，输入"Terminal"，按回车；或按 Command + Shift + U，在"实用工具"中找到终端。

Step 2：执行一键安装命令

# macOS 一键安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

国内加速：

# 使用 OpenClaw-CN 国内镜像
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

安装过程：

• 自动检测 macOS 芯片类型（Intel/Apple Silicon）
• 根据芯片类型下载对应版本
• macOS 可能要求输入开机密码（输入时不显示字符，直接回车即可）
• 全程 2-5 分钟（取决于网速）

成功标志：

✓ OpenClaw installed successfully ✓ Node.js 22.x detected ✓ Apple Silicon optimization enabled

3.2.2 方式二：Homebrew 安装（推荐，方便管理）

前提：已安装 Homebrew

检查是否安装 Homebrew：

brew --version

安装 Homebrew（如未安装）：

/bin/bash -c"$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

使用 Homebrew 安装 OpenClaw：

# 更新 Homebrew
brew update

# 安装 OpenClaw
brew install openclaw

优势：

• 方便版本管理（brew upgrade openclaw）
• 自动处理依赖关系
• 卸载方便（brew uninstall openclaw）

3.2.3 方式三：包管理器安装

npm 安装：

npm install -g openclaw@latest

pnpm 安装（推荐）：

# 安装 pnpm（如果未安装）
npm install -g pnpm

# 使用 pnpm 安装
pnpm add -g openclaw@latest

3.3 Linux 系统安装

3.3.1 方式一：一键脚本安装（5 分钟搞定）

Step 1：打开终端

• Ubuntu/Debian：按 Ctrl + Alt + T
• Fedora：按 Ctrl + Alt + F2
• Arch：按 Ctrl + Alt + T

Step 2：执行一键安装命令

# Linux 一键安装脚本
curl -fsSL https://openclaw.ai/install.sh | bash

国内加速：

# 使用 OpenClaw-CN 国内镜像
curl -fsSL https://open-claw.org.cn/install-cn.sh | bash

安装过程说明：

• 自动检测 Linux 发行版
• 自动安装依赖（Node.js、Git 等）
• 配置系统服务（systemd）
• 全程 3-8 分钟

3.3.2 包管理器安装

npm 安装：

npm install -g openclaw@latest

pnpm 安装（推荐）：

# 安装 pnpm
npm install -g pnpm

# 使用 pnpm 安装
pnpm add -g openclaw@latest

yarn 安装：

yarn global add openclaw@latest

3.4 Docker 容器安装（适合生产环境）

优点：隔离环境、便于部署、资源控制

3.4.1 前提条件

已安装 Docker Engine 20+ 或 Docker Desktop

检查 Docker 版本：

docker --version

3.4.2 使用 Docker 运行

方式一：命令行运行

# 拉取最新镜像
docker pull openclaw/openclaw:latest

# 运行容器
docker run -d\
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  --restart unless-stopped \
  openclaw/openclaw:latest

参数说明：

• -d：后台运行
• --name：容器名称
• -p：端口映射（主机端口：容器端口）
• -v：数据卷映射（本地目录：容器目录）
• --restart：重启策略

方式二：Docker Compose（推荐） 创建 docker-compose.yml 文件：

version:'3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      -"18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped
    environment:
      - TZ=Asia/Shanghai  # 时区设置
    env_file:
      - ~/.openclaw/.env

启动服务：

# 启动容器
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

# 重启服务
docker-compose restart

3.4.3 进入容器调试

# 进入容器内部
docker exec -it openclaw bash

# 查看容器内文件
docker exec openclaw ls -la ~/.openclaw

# 执行容器内命令
docker exec openclaw openclaw --version

3.5 初始化配置（Onboarding）

无论使用哪种安装方式，安装完成后都需要执行初始化向导。

执行命令：

openclaw onboard --install-daemon

向导包含以下步骤：

3.5.1 选择 AI 供应商

向导会列出支持的模型供应商：

• Anthropic (Claude Pro/Max)
• OpenAI (GPT-4/GPT-4o)
• Google (Gemini)
• Alibaba Cloud (通义千问)
• Local (Ollama)

选择建议：

• 国内用户：优先选择阿里云百炼（通义）或 DeepSeek（速度快、延迟低）
• 国际用户：Claude Pro（长上下文强）或 GPT-4o（多模态能力强）
• 隐私优先：选择 Local (Ollama)，完全离线可用

3.5.2 添加 API Key

Claude API Key 获取：

1. 访问：https://console.anthropic.com/
2. 注册/登录账户
3. 进入"API Keys"页面
4. 点击"Create Key"
5. 复制生成的 Key（格式：sk-ant-xxxxxxxxxx）
6. 粘贴到向导中

GPT API Key 获取：

1. 访问：https://platform.openai.com/api-keys
2. 登录 OpenAI 账户
3. 点击"Create new secret key"
4. 复制 Key（格式：sk-proj-xxxxxxxxxx）

阿里云百炼 API Key 获取：

1. 访问：https://dashscope.aliyuncs.com/
2. 登录阿里云账号（需实名认证）
3. 进入"API-KEY 管理"→"创建 API-KEY"
4. 保存 Access Key ID 和 Access Key Secret（Secret 仅在创建时可见）

安全提示：

• API Key 仅存储在本地 .env 文件中
• 不会上传到 OpenClaw 官方服务器
• 建议定期轮换（每 3 个月）

3.5.3 连接聊天平台

WhatsApp 连接：

1. 向导选择"WhatsApp"
2. 显示二维码
3. 手机 WhatsApp 扫描二维码
4. 等待连接成功提示

Telegram 连接：

1. 向导选择"Telegram"
2. 粘贴 Bot Token（从@BotFather 获取）
3. 测试连接

获取 Telegram Bot Token：

1. 在 Telegram 中搜索 @BotFather
2. 发送 /newbot 命令
3. 按提示设置 Bot 名称和用户名
4. 复制生成的 Token（格式：1234567890:ABCdefGHIjklMNOpqrsTUVwxyz）

飞书连接（国内用户推荐）：

1. 向导选择"飞书"
2. 粘贴 App ID 和 App Secret（从飞书开放平台获取）
3. 测试连接

3.5.4 发送测试消息

连接成功后，发送第一条测试消息：

"你能做什么？"

如果 OpenClaw 回复，说明配置成功，可以正常使用了！

3.6 启动网关服务

3.6.1 启动方式

方式一：直接启动（前台运行）

# 使用默认端口 18789 启动
openclaw gateway

# 指定端口启动
openclaw gateway --port 18789

# 启用详细日志
openclaw gateway --verbose

方式二：守护进程启动（后台运行，推荐）

# 使用 onboard 向导安装守护进程
openclaw onboard --install-daemon

# 手动安装守护进程（Linux）
sudo systemctl enable --now openclaw

# macOS 使用 launchd（已自动配置）
sudo launchctl bootstrap gui/$(id -u)/openclaw

方式三：启动并打开控制台

# 启动网关
openclaw gateway --port 18789

# 打开 Web 控制台（自动打开浏览器）
openclaw dashboard

# 或手动访问
# 浏览器输入：http://localhost:18789

3.6.2 验证服务状态

# 检查网关是否运行
openclaw gateway status

# 查看日志
openclaw logs --follow

# 深度诊断
openclaw doctor

Web 控制台功能：

• Dashboard：主控制面板，查看状态和配置
• Skills：技能市场，浏览和安装插件
• Chat：实时对话窗口，测试 AI 响应
• Settings：高级配置，模型切换、权限管理

四、基础功能演示：核心 API 详解

4.1 CLI 命令体系

OpenClaw 提供完整的 CLI 命令体系，分为以下几大类：

4.1.1 网关管理命令

# 启动网关
openclaw gateway [options]

# 常用选项：
# --port<端口号>  指定监听端口（默认 18789）
# --verbose       启用详细日志输出
# --daemon        后台运行（守护进程）
# --config<配置文件路径>  指定自定义配置文件

# 示例：启动自定义端口
openclaw gateway --port 8080 --verbose

# 停止网关
openclaw gateway stop

# 重启网关
openclaw gateway restart

4.1.2 通道管理命令

# 列出所有已配置的通道
openclaw channels list

# 查看通道状态和健康检查
openclaw channels status --probe

# 添加新通道
openclaw channels add --type telegram --token"your-bot-token"

# 登录通道（显示二维码）
openclaw channels login --type whatsapp

# 登出通道
openclaw channels logout --type discord

# 查看通道日志
openclaw channels logs --type telegram --follow

4.1.3 消息发送命令

# 发送消息到指定会话
openclaw message send --to<目标>--message"消息内容"

# 参数说明：
# --to<目标>     目标接收者（手机号、@username、会话 ID）
# --message<内容> 消息文本
# --session<会话 ID> 指定会话（可选）

# 示例：发送到 Telegram
openclaw message send --to @username --message"帮我整理文件"

# 示例：发送到 WhatsApp
openclaw message send --to +1234567890 --message"生成周报"

4.1.4 Agent 相关命令

# 执行 Agent 任务
openclaw agent --message"指令内容"[options]

# 常用选项：
# --thinking<级别> 思考深度：low/medium/high
# --session<会话 ID> 指定会话
# --model<模型名称> 指定使用的模型

# 示例：高思考深度执行任务
openclaw agent --message"分析这个项目" --thinking high

# 示例：使用特定模型
openclaw agent --message"翻译这段话" --model gpt-4o

4.1.5 配置管理命令

# 启动交互式配置向导
openclaw configure

# 设置配置值
openclaw config set<配置路径><值>

# 示例：设置默认端口
openclaw config set gateway.port 18789

# 示例：设置默认模型
openclaw config set model.defaultModel claude-sonnet-4

# 示例：设置白名单
openclaw config set gateway.auth.allowFrom "+1234567890"

# 获取配置值
openclaw config get <配置路径>

# 示例：查看当前端口配置
openclaw config get gateway.port

# 查看所有配置
openclaw config list

4.1.6 定时任务命令

# 添加定时任务
openclaw cronadd --name<任务名>--cron<cron 表达式>--message"指令"[options]

# 参数说明：
# --name<任务名>   任务唯一标识
# --cron<表达式>   Cron 表达式（如"0 9 * * *"表示每天 9 点）
# --message<指令>  要执行的消息内容
# --at<时间>       一次性执行时间
# --every<间隔>    重复间隔（如"3600000"表示每 1 小时）
# --tz<时区>       时区（默认 Asia/Shanghai）
# --session<会话>  指定会话
# --delete-after-run 执行后自动删除

# 示例 1：每天 9 点提醒开会
openclaw cronadd \
  --name"Morning Reminder" \
  --cron"0 9 * * *" \
  --message"提醒我开会" \
  --session main

# 示例 2：每小时检查服务器状态
openclaw cronadd \
  --name"Server Check" \
  --every 3600000 \
  --message"检查服务器状态，异常则通知我" \
  --session monitoring

# 示例 3：特定时间执行备份
openclaw cronadd \
  --name"Daily Backup" \
  --at"2026-03-15T02:00:00+08:00" \
  --message"执行数据库备份" \
  --session backup

# 列出所有任务
openclaw cron list

# 查看任务状态
openclaw cron status --id<任务 ID>

# 立即执行任务
openclaw cron run --id<任务 ID>

# 编辑任务
openclaw cron edit --id<任务 ID>--cron"0 10 * * *"

# 删除任务
openclaw cron delete --id<任务 ID>

4.1.7 诊断与维护命令

# 查看版本号
openclaw --version

# 系统健康检查
openclaw doctor

# 查看日志
openclaw logs [options]

# 选项：
# --follow        实时跟踪日志（Ctrl+C 退出）
# --since<时间>   从指定时间开始查看
# --tail<行数>    只显示最后 N 行
# --session<会话> 查看特定会话日志

# 示例：实时查看日志
openclaw logs --follow

# 示例：查看最近 100 行日志
openclaw logs --tail 100

# 清理缓存
openclaw cache clear

# 重置配置
openclaw reset

4.2 核心 API 详解（开发者视角）

OpenClaw 提供 RESTful API，支持二次开发和集成。

4.2.1 Gateway API

基础 URL：

http://localhost:18789/api

认证方式：Token-based 认证

// 请求示例（JavaScript）
const gatewayToken = "your-gateway-token"; // 从配置中获取

async function sendMessage(message) {
  const response = await fetch('http://localhost:18789/api/messages', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${gatewayToken}`
    },
    body: JSON.stringify({
      message: message,
      session: 'main'
    })
  });
  return response.json();
}

4.2.2 Channel API

连接通道：

// Telegram 通道配置
const channelConfig = {
  type: 'telegram',
  token: 'your-bot-token'
};

// 发送请求到 Gateway
await fetch('http://localhost:18789/api/channels', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${gatewayToken}`
  },
  body: JSON.stringify(channelConfig)
});

4.2.3 Webhook API

Webhook 允许外部服务推送消息到 OpenClaw：

// Webhook 配置
const webhookConfig = {
  url: 'https://your-server.com/webhook',
  secret: 'your-webhook-secret',
  events: ['message', 'agent_task_completed']
};

// 注册 Webhook
await fetch('http://localhost:18789/api/webhooks', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${gatewayToken}`
  },
  body: JSON.stringify(webhookConfig)
});

4.3 常用操作实战

4.3.1 文件操作演示

场景：批量整理下载文件夹

指令：

# 通过 Telegram 发送指令到 OpenClaw
"帮我把下载文件夹中的所有 PDF 文件移动到 Documents/PDF 文件夹，并按下载日期分类"

执行流程：

1. OpenClaw 识别"整理文件"意图
2. 调用文件系统工具扫描 ~/Downloads 目录
3. 筛选出所有.pdf 文件
4. 读取文件元数据获取下载日期
5. 按日期创建子文件夹（2026-01、2026-02 等）
6. 移动文件到对应文件夹
7. 返回执行结果："已整理 156 个 PDF 文件，创建了 12 个子文件夹"

代码示例（自定义 Skill 实现）：

// ~/.openclaw/skills/file-organizer.ts
import { FileSystemTool } from '@openclaw/tools';

export default async function organizeFiles(args: any) {
  const { sourceDir = '~/Downloads', targetDir = '~/Documents/PDF' } = args;

  // 1. 扫描源目录
  const files = await FileSystemTool.listFiles(sourceDir, {
    pattern: '*.pdf',
    recursive: true
  });

  // 2. 按日期分类
  const organized: Record<string, any[]> = {};
  for (const file of files) {
    const date = new Date(file.stats.mtime);
    const monthKey = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}`;
    if (!organized[monthKey]) {
      organized[monthKey] = [];
    }
    organized[monthKey].push(file);
  }

  // 3. 创建子文件夹并移动文件
  for (const [month, files] of Object.entries(organized)) {
    const monthDir = `${targetDir}/${month}`;
    await FileSystemTool.ensureDir(monthDir);
    for (const file of files) {
      await FileSystemTool.moveFile(file.path, `${monthDir}/${file.name}`);
    }
  }

  return {
    success: true,
    message: `已整理${files.length}个 PDF 文件，创建了${Object.keys(organized).length}个月份文件夹`,
    details: organized
  };
}

4.3.2 终端命令执行演示

场景：服务器状态检查

指令：

# 通过 Telegram 发送指令
"检查服务器状态，CPU 使用率超过 80% 或磁盘剩余小于 10GB 时发送警报"

执行流程：

1. 执行 Shell 命令获取 CPU 使用率：top -bn1 | grep "Cpu(s)" | awk '{print $2}'
2. 执行命令获取磁盘剩余：df -h / | awk '{print $4}'
3. 判断是否超过阈值
4. 超过阈值则通过 Telegram 发送警报

代码示例：

// ~/.openclaw/skills/server-monitor.ts
import { TerminalTool } from '@openclaw/tools';

export default async function checkServerStatus(args: any) {
  const { cpuThreshold = 80, diskThreshold = 10 } = args;

  // 获取 CPU 使用率
  const cpuResult = await TerminalTool.execute('top -bn1 | grep "Cpu(s)" | awk \'{print $2}\'');
  const cpuUsage = parseFloat(cpuResult.stdout.trim());

  // 获取磁盘剩余空间
  const diskResult = await TerminalTool.execute('df -h / | awk \'{print $4}\'');
  const diskFree = parseFloat(diskResult.stdout.trim());

  // 判断并发送警报
  let alert = '';
  if (cpuUsage > cpuThreshold) {
    alert += `CPU 使用率${cpuUsage}%，超过阈值${cpuThreshold}%\n`;
  }
  if (diskFree < diskThreshold) {
    alert += `磁盘剩余${diskFree}GB，低于阈值${diskThreshold}GB\n`;
  }

  if (alert) {
    return {
      success: true,
      message: `⚠️ 服务器状态警报：\n${alert}`,
      details: { cpuUsage, diskFree }
    };
  }

  return {
    success: true,
    message: `服务器状态正常：CPU ${cpuUsage}%，磁盘剩余 ${diskFree}GB`,
    details: { cpuUsage, diskFree }
  };
}

4.3.3 浏览器自动化演示

场景：批量填写表单

指令：

# 通过 Telegram 发送指令
"帮我打开这个网站：https://example.com/form，填写表单，姓名填"张三"，邮箱填"[email protected]"，提交后截图"

执行流程：

1. 使用 Playwright 或 Puppeteer 打开网站
2. 等待页面加载完成
3. 查找表单字段（通过选择器）
4. 填充姓名和邮箱
5. 提交表单
6. 等待提交成功
7. 截图并返回

代码示例：

// ~/.openclaw/skills/form-filler.ts
import { BrowserTool } from '@openclaw/tools';

export default async function fillForm(args: any) {
  const { url = 'https://example.com/form', fields = { name: '张三', email: '[email protected]' } } = args;

  // 1. 打开网站
  const page = await BrowserTool.open(url, {
    waitUntil: 'networkidle'
  });

  // 2. 填写表单字段
  await page.fill('input[name="name"]', fields.name);
  await page.fill('input[name="email"]', fields.email);

  // 3. 提交表单
  await page.click('button[type="submit"]');

  // 4. 等待提交成功
  await page.waitForSelector('.success-message', { timeout: 10000 });

  // 5. 截图
  const screenshot = await page.screenshot({
    path: '~/.openclaw/screenshots/form-submission.png',
    fullPage: true
  });

  return {
    success: true,
    message: '表单填写完成并已截图',
    screenshot: screenshot.path
  };
}

4.3.4 邮件发送演示

场景：自动发送报告

指令：

"读取 Documents/report.docx，提取本周数据，生成邮件发送给 [email protected]"

代码示例：

// ~/.openclaw/skills/email-sender.ts
import { EmailTool, FileSystemTool } from '@openclaw/tools';

export default async function sendReport(args: any) {
  const { reportPath = 'Documents/report.docx', recipient = '[email protected]' } = args;

  // 1. 读取报告文件
  const reportContent = await FileSystemTool.readFile(reportPath);

  // 2. 提取关键信息
  const summary = await Agent.process(reportContent, {
    task: 'extract_weekly_data'
  });

  // 3. 发送邮件
  await EmailTool.send({
    to: recipient,
    subject: '本周工作报告',
    body: summary,
    attachments: [reportPath]
  });

  return {
    success: true,
    message: `报告已发送至${recipient}`,
    details: { summary, attachments: [reportPath] }
  };
}

五、实战案例：计算机视觉应用

5.1 案例一：智能监控系统

5.1.1 项目背景

业务场景：车间流水线实时监控

传统方式痛点：

• 需要人工 24 小时盯守
• 发现缺陷后手动停机，反应慢
• 数据统计手动计算，容易出错

5.1.2 OpenClaw 解决方案

系统架构：

摄像头 → 视觉模型识别 → OpenClaw 决策 → 动作执行（停机/通知） → 结果反馈

技术栈选择：

• 视觉模型：YOLOv8（实时目标检测，速度快）
• 决策模型：Claude Sonnet 4（理解复杂场景）
• 执行工具：终端命令、邮件通知、WebSocket 推送

5.1.3 完整实现代码

Step 1：创建视觉检测 Skill 创建文件 ~/.openclaw/skills/vision-monitor.ts：

import { executeCommand } from '@openclaw/tools';

interface DetectionResult {
  class_name: string;      # 类别名称（如"缺陷"、"正常"）
  confidence: number;      # 置信度（0-1）
  bbox: [number, number];  # 边界框 [x, y, width, height]
}

export default async function detectDefect(imagePath: string) {
  // 调用 YOLOv8 模型进行检测
  const result = await executeCommand(`yolo predict --source ${imagePath} --json`);
  const detections: DetectionResult[] = JSON.parse(result.stdout);

  // 过滤低置信度结果
  const highConfidenceDetections = detections.filter(d => d.confidence > 0.7);

  // 判断是否有缺陷
  const hasDefect = highConfidenceDetections.some(d =>
    d.class_name === 'defect' || d.class_name === 'scratch' || d.class_name === 'dent'
  );

  return {
    success: true,
    hasDefect,
    detections: highConfidenceDetections,
    message: hasDefect ? `发现缺陷，置信度${Math.max(...detections.map(d => d.confidence)).toFixed(2)}` : '检测正常'
  };
}

Step 2：创建决策逻辑 Skill 创建文件 ~/.openclaw/skills/decision-maker.ts：

export default async function makeDecision(detectionResult: any) {
  const { hasDefect, detections, confidence } = detectionResult;

  // 决策逻辑
  if (hasDefect && confidence > 0.85) {
    // 高置信度缺陷 → 立即停机
    return {
      action: 'STOP_PRODUCTION_LINE',
      reason: `检测到高置信度缺陷 (${confidence.toFixed(2)})，立即停机`,
      priority: 'CRITICAL'
    };
  } else if (hasDefect && confidence <= 0.85) {
    // 中置信度缺陷 → 记录并报警
    return {
      action: 'LOG_AND_ALERT',
      reason: `检测到疑似缺陷 (${confidence.toFixed(2)})，记录并通知质检员`,
      priority: 'HIGH'
    };
  } else {
    // 无缺陷 → 继续生产
    return {
      action: 'CONTINUE_PRODUCTION',
      reason: '检测正常，继续生产',
      priority: 'NORMAL'
    };
  }
}

Step 3：创建动作执行 Skill 创建文件 ~/.openclaw/skills/action-executor.ts：

import { executeCommand, sendEmail } from '@openclaw/tools';

export default async function executeDecision(decision: any) {
  const { action, reason, priority } = decision;

  switch (action) {
    case 'STOP_PRODUCTION_LINE':
      // 立即停机
      await executeCommand('systemctl stop production-line');
      await sendEmail({
        to: '[email protected]',
        subject: '【紧急】生产线已停机',
        body: `停机原因：${reason}\n停机时间：${new Date().toLocaleString()}`
      });
      break;
    case 'LOG_AND_ALERT':
      // 记录并报警
      await executeCommand(`echo "${reason}" >> /var/log/defects.log`);
      await executeCommand('notify-send "质检员请注意：${reason}"');
      break;
    case 'CONTINUE_PRODUCTION':
      // 继续生产
      await executeCommand('systemctl start production-line');
      break;
  }

  return {
    success: true,
    message: `已执行动作：${action}`,
    details: decision
  };
}

Step 4：注册 Skill 编辑 ~/.openclaw/skills/skills.json：

{
  "vision-monitor": {
    "name": "智能监控系统",
    "description": "结合 YOLO 视觉检测与 OpenClaw 决策的流水线监控系统",
    "version": "1.0.0",
    "skills": [
      "vision-monitor.detectDefect",
      "vision-monitor.makeDecision",
      "vision-monitor.executeAction"
    ],
    "dependencies": {
      "models": ["yolo"],
      "llm": "claude-sonnet-4"
    }
  }
}

5.1.4 实际运行效果

测试指令：

# 通过 Telegram 发送指令
"开始流水线监控，检测间隔 30 秒，缺陷置信度阈值 0.7"

执行流程：

1. OpenClaw 启动定时任务，每 30 秒检测一次
2. 调用 YOLO 模型进行实时检测
3. Claude 分析检测结果，判断决策
4. 根据决策执行相应动作（停机、记录、继续）
5. 记录所有检测和决策到日志

效果对比：

指标	传统方式	OpenClaw 自动化
响应时间	5-10 分钟	<30 秒
人工成本	3 班×24 小时	需配置时人工审核
不良率	5-8%	2-3%（及时发现）
误报率	15-20%	<5%（AI 分析）

5.2 案例二：智能文档生成系统

5.2.1 项目背景

业务场景：技术文档自动生成

传统方式痛点：

• 手动编写文档，耗时耗力
• 格式不统一，维护困难
• 更新不及时，版本混乱

5.2.2 OpenClaw 解决方案

技术架构：

代码仓库 → 代码分析 → 内容提取 → 模板生成 → 输出文档 → 自动部署

核心技术：

• 代码解析：Tree-sitter 语法分析，提取函数签名、注释
• 自然语言生成：LLM 生成文档内容
• 模板渲染：Markdown/HTML 模板生成
• 版本管理：Git 标签管理，自动生成 CHANGELOG

5.2.3 完整实现代码

Step 1：创建代码解析 Skill 创建文件 ~/.openclaw/skills/code-analyzer.ts：

import { executeCommand } from '@openclaw/tools';

interface FunctionInfo {
  name: string;          # 函数名称
  signature: string;     # 函数签名
  description: string;   # 注释描述
  file_path: string;     # 文件路径
  line_number: number;   # 行号
}

export default async function analyzeCode(projectPath: string) {
  // 递归扫描项目文件
  const files = await executeCommand(`find ${projectPath} -type f \( -name "*.ts" -o -name "*.tsx" \)`);
  const functions: FunctionInfo[] = [];

  // 解析每个文件
  for (const file of files.stdout.split('\n')) {
    // 使用 Tree-sitter 提取函数
    const parsed = await parseFileWithTreeSitter(file);
    functions.push(...parsed.functions);
  }

  return {
    success: true,
    total_functions: functions.length,
    files_analyzed: files.stdout.split('\n').length,
    functions
  };
}

Step 2：创建文档生成 Skill 创建文件 ~/.openclaw/skills/doc-generator.ts：

import { generateWithLLM } from '@openclaw/llm';

export default async function generateDocumentation(functions: FunctionInfo[], template: 'swagger' | 'readme') {
  // 根据模板类型生成文档
  let prompt = '';
  if (template === 'swagger') {
    prompt = `根据以下函数列表生成 Swagger 格式的 API 文档：\n${JSON.stringify(functions, null, 2)}`;
  } else if (template === 'readme') {
    prompt = `根据以下函数列表生成 README 文档，包含：安装、使用、示例：\n${JSON.stringify(functions, null, 2)}`;
  }

  // 调用 LLM 生成
  const documentation = await generateWithLLM(prompt);
  return {
    success: true,
    documentation,
    template
  };
}

Step 3：创建版本管理 Skill 创建文件 ~/.openclaw/skills/version-manager.ts：

import { executeCommand, git } from '@openclaw/tools';

export default async function updateVersion(projectPath: string, version: string) {
  // 1. 创建 Git 标签
  await executeCommand(`cd ${projectPath} && git tag v${version}`);

  // 2. 生成 CHANGELOG
  const changelog = await generateWithLLM(`生成 v${version}版本的 CHANGELOG.md，包含：新功能、修复、改进`);
  await executeCommand(`cd ${projectPath} && cat > CHANGELOG.md << 'EOF'\n${changelog}\nEOF`);

  // 3. 提交并推送
  await executeCommand(`cd ${projectPath} && git add CHANGELOG.md && git commit -m "Release v${version}" && git push origin main --tags`);

  return {
    success: true,
    message: `版本 v${version}已发布并推送`,
    version,
    changelog
  };
}

Step 4：创建主控 Skill 创建文件 ~/.openclaw/skills/doc-system.ts：

export default async function runDocSystem(args: any) {
  const { action = 'generate', projectPath = '~/projects/my-api' } = args;

  switch (action) {
    case 'generate':
      // 1. 分析代码
      const analysis = await analyzeCode(projectPath);
      // 2. 生成文档
      const docs = await generateDocumentation(analysis.functions, 'swagger');
      // 3. 保存文档
      await saveFiles(docs);
      return {
        success: true,
        message: `文档生成完成，共${analysis.total_functions}个函数`,
        details: analysis
      };
    case 'release':
      const version = args.version || new Date().toISOString().split('T')[0].replace(/-/g, '.');
      const result = await updateVersion(projectPath, version);
      return result;
    default:
      return {
        success: false,
        message: '未知操作，请使用 generate 或 release'
      };
  }
}

5.2.4 使用效果

测试指令：

# 生成 API 文档
"分析~/projects/my-api 代码，生成 Swagger 格式的 API 文档"

# 发布新版本
"发布 v1.2.0 版本，生成 CHANGELOG"

效果对比：

指标	手动方式	OpenClaw 自动化
文档生成时间	4-8 小时	15-30 分钟
准确性	70-80%	90-95%（AI 生成更全面）
一致性	格式不统一	模板化，风格统一
更新及时性	依赖个人习惯	自动化，定时触发

六、常见问题解决：避坑指南

6.1 安装相关问题

6.1.1 问题：Windows 安装时报"执行策略禁止"

错误信息：

无法加载文件，因为在此系统上禁止运行脚本 execution of scripts is disabled on this system

原因：PowerShell 默认执行策略为 Restricted

解决方案：

# 临时允许脚本执行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# 永久允许（不推荐）
Set-ExecutionPolicy Unrestricted -Scope CurrentUser

6.1.2 问题：macOS 安装时报"无法验证开发者"

错误信息：

无法验证开发者，应用已损坏 app is damaged and can't be opened

原因：安全设置阻止应用运行

解决方案：

# 方案 1：右键打开
# 找到 OpenClaw 应用，右键选择"打开"
# 在"安全与隐私"中点击"仍要打开"

# 方案 2：移除隔离属性
xattr -d com.apple.quarantine /path/to/openclaw

# 方案 3：重新签名（有开发者证书时）
codesign --force --deep --sign /path/to/openclaw

6.1.3 问题：Linux 安装时报"权限不足"

错误信息：

EACCES: permission denied npm ERR! code EACCES

原因：非 root 用户写入系统目录

解决方案：

# 使用 sudo 安装
sudo npm install -g openclaw@latest

# 或使用 nvm 免 root 安装
nvm install 22
nvm use 22
npm install -g openclaw@latest

6.2 运行相关问题

6.2.1 问题：启动后浏览器无法打开控制台

错误信息：

无法访问此网站 can't reach this site

排查步骤：

Step 1：检查网关状态

openclaw gateway status

Step 2：检查端口是否监听

# macOS/Linux
lsof -i:18789

# Windows PowerShell
Get-NetTCPConnection -LocalPort 18789 -State Listen -ErrorAction SilentlyContinue

Step 3：检查防火墙

# macOS（系统偏好设置 → 安全性与隐私 → 防火墙）

# Linux（ufw）
sudo ufw status
sudo ufw allow 18789

# Windows（控制面板 → Windows Defender 防火墙 → 允许应用通过防火墙）

Step 4：手动访问

# 浏览器直接访问
http://localhost:18789
http://127.0.0.1:18789

# 使用指定端口（如果修改过）
http://localhost:18790

6.2.2 问题：模型调用失败或响应超时

错误信息：

请求超时 request timeout API Key 无效 invalid API key

排查步骤：

Step 1：检查 API Key 配置

# 查看配置文件
cat ~/.openclaw/.env

# 或使用命令查看
openclaw config get model.apiKey

Step 2：验证 API Key

# Claude API 测试
curl https://api.anthropic.com/v1/messages \
  -H"x-api-key: your-api-key" \
  -H"Content-Type: application/json" \
  -d'{"model":"claude-3-5-sonnet-20250214","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

# GPT API 测试
curl https://api.openai.com/v1/chat/completions \
  -H"Authorization: Bearer your-api-key" \
  -H"Content-Type: application/json" \
  -d'{"model":"gpt-4","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'

Step 3：检查网络连接

# 测试 API 可达性
curl -I https://api.anthropic.com/v1/messages --max-time 5

# 检查 DNS 解析
nslookup api.anthropic.com

# 检查代理设置
echo $http_proxy
echo $https_proxy

Step 4：调整超时设置

# 修改配置增加超时时间
openclaw config set llm.timeout 60000 # 60 秒
openclaw config set llm.retry 3       # 重试 3 次

6.2.3 问题：通道连接失败

症状：Telegram 消息发送后无响应；WhatsApp 二维码无法显示；Discord 机器人不在线

排查步骤：

Step 1：检查通道状态

openclaw channels status --probe

Step 2：查看通道日志

# Telegram 日志
openclaw channels logs --type telegram --follow

# WhatsApp 日志
openclaw channels logs --type whatsapp --follow

# Discord 日志
openclaw channels logs --type discord --follow

Step 3：重新连接通道

# 登出通道
openclaw channels logout --type telegram

# 重新登录
openclaw channels login --type telegram

6.2.4 问题：Skill 加载失败

错误信息：

Skill 加载失败 skill load failed 找不到模块 module not found

排查步骤：

Step 1：检查 Skill 文件

# 列出所有 Skill
ls -la ~/.openclaw/skills/

# 检查 skills.json 格式
cat ~/.openclaw/skills/skills.json | python3 -m json.tool

Step 2：检查依赖

# 检查 Skill 依赖是否安装
openclaw doctor

# 查看详细诊断
openclaw doctor --deep

Step 3：重新加载 Skill

# 重启网关使 Skill 生效
openclaw gateway restart

# 或手动重新加载
openclaw skills reload

6.3 性能优化问题

6.3.1 问题：响应速度慢

可能原因：网络延迟高；模型选择不当（大模型处理小任务）；本地硬件性能不足

优化方案：

方案 1：模型选择策略

# 配置多模型，根据任务复杂度自动选择
openclaw config set model.routing "auto"

# 配置简单任务模型（快速响应）
openclaw config set model.simple "claude-3-5-haiku-20241022"

# 配置复杂任务模型（高智能）
openclaw config set model.complex "claude-sonnet-4-20250214"

方案 2：启用模型缓存

# 启用缓存减少 API 调用
openclaw config set model.cache true

# 设置缓存有效期（秒）
openclaw config set model.cacheTTL 1800 # 30 分钟

# 设置缓存大小
openclaw config set model.cacheMaxSize 100 # 最多缓存 100 个请求

方案 3：并发处理

# 启用 Agent 并发
openclaw config set agents.concurrency 2

# 配置消息批处理
openclaw config set gateway.batchSize 5

6.3.2 问题：内存占用高

可能原因：历史会话未清理；向量数据库过大；缓存数据过多

优化方案：

方案 1：会话压缩

# 配置会话压缩策略
openclaw config set memory.compression true

# 设置压缩阈值
openclaw config set memory.compressionThreshold 2000 # 超过 2000 token 开始压缩

# 设置压缩比例
openclaw config set memory.compressionRatio 0.8 # 保留 80% 重要信息

方案 2：定期清理

# 手动清理缓存
openclaw cache clear

# 清理过期会话（超过 7 天）
openclaw memory cleanup --days 7

方案 3：向量数据库优化

# 配置向量数据库大小限制
openclaw config set memory.maxVectors 10000 # 最多 10000 条向量

# 配置向量 TTL
openclaw config set memory.vectorTTL 2592000 # 30 天

6.4 安全相关问题

6.4.1 问题：权限过大风险

风险：文件误删、系统异常

防护措施：

措施 1：启用沙箱模式

# 配置沙箱限制
openclaw config set agents.sandbox true

# 配置沙箱限制路径
openclaw config set agents.sandboxPath ~/sandbox

措施 2：操作审批机制

# 启用高风险操作审批
openclaw config set agents.approval true

# 配置审批通道
openclaw config set agents.approvalChannel "telegram"

措施 3：操作日志审计

# 启用操作日志
openclaw config set agents.auditLog true

# 查看操作日志
openclaw logs --filter"file 操作，terminal 执行"

6.4.2 问题：API Key 泄露风险

防护措施：

措施 1：使用环境变量

# 设置 API Key 为环境变量
export ANTHROPIC_API_KEY="your-key"

# 在配置文件中引用
{
  "models": {
    "apiKey": "${ANTHROPIC_API_KEY}"
  }
}

措施 2：定期轮换

# 设置轮换提醒
openclaw cronadd --name"API 轮换提醒" --cron"0 0 1 */3 *" --message"提醒轮换 API Key"

# 每季度轮换一次

措施 3：访问限制

# 配置 IP 白名单
openclaw config set gateway.auth.allowFrom ["192.168.1.100", "+1234567890"]

# 配置时间限制
openclaw config set gateway.auth.allowHours "09:00-18:00"

七、进阶应用：自定义技能开发

7.1 Skill 开发基础

OpenClaw 的 Skill 机制允许扩展其核心能力。

7.1.1 Skill 文件结构

标准目录结构：

~/.openclaw/
├── skills/
│   ├── skills.json             # Skill 注册表
│   ├── skill-1/                # Skill 1
│   │   ├── skill.ts            # 主逻辑文件
│   │   ├── skill.md            # 说明文档
│   │   └── package.json        # 依赖管理
│   └── skill-2/                # Skill 2
└── agents/
    └── main/
        ├── AGENTS.md           # Agent 定义
        ├── SOUL.md             # Agent 人格
        └── MEMORY.md           # 初始记忆

skills.json 示例：

{
  "skill-1": {
    "name": "文件整理助手",
    "description": "自动整理和分类文件",
    "version": "1.0.0",
    "author": "your-name",
    "skills": [
      "skill-1.organize",
      "skill-1.analyze"
    ],
    "dependencies": {
      "tools": ["file-system", "terminal"],
      "llm": "claude-sonnet-4"
    },
    "permissions": {
      "allowFileSystem": true,
      "allowTerminal": true
    }
  }
}

7.1.2 Skill 开发示例

Skill 主文件（skill.ts）：

import { ToolRegistry } from '@openclaw/core';

export default async function skillMain(args: any) {
  const { action = 'organize', path = '~/Downloads' } = args;

  // 使用工具注册表调用工具
  const fileTool = ToolRegistry.get('file-system');
  const llm = ToolRegistry.get('llm');

  // 1. 扫描目录
  const files = await fileTool.listFiles(path);

  // 2. 使用 LLM 分析分类
  const categories = await llm.generate({
    prompt: `将以下文件按类型分类：${JSON.stringify(files)}`,
    model: 'claude-3-5-haiku'
  });

  // 3. 执行整理操作
  for (const [category, fileList] of Object.entries(categories)) {
    const categoryPath = `${path}/${category}`;
    await fileTool.ensureDir(categoryPath);
    for (const file of fileList) {
      await fileTool.moveFile(file.path, `${categoryPath}/${file.name}`);
    }
  }

  return {
    success: true,
    message: `已整理${files.length}个文件到${Object.keys(categories).length}个分类`,
    details: categories
  };
}

Skill 元数据（skill.md）：

# 文件整理助手

## 功能描述
自动扫描指定目录，根据文件类型、修改时间等特征智能分类，并移动到对应文件夹。

## 使用方法

帮我把 ~/Downloads 文件夹整理一下

## 参数说明
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | 操作类型：organize/analyze |
| path | string | 否 | 目标路径，默认~/Downloads |

## 返回结果
```json
{
  "success": true,
  "message": "已整理 156 个文件",
  "details": { "文档": 45, "图片": 32, "视频": 12 }
}

依赖

权限要求

7.1.3 Skill 测试与部署

本地测试：

# 加载 Skill 测试
openclaw skills test --path ~/.openclaw/skills/skill-1

# 验证依赖
openclaw doctor --check-skills

# 查看 Skill 列表
openclaw skills list

发布到社区（可选）：

openclaw skills install https://github.com/your-repo/skill-1

7.2 Agent 配置

7.2.1 Agent 定义（AGENTS.md）

# 文件整理助手

## 人格定义
我是一个专业的文件整理助手，擅长根据文件类型、时间特征智能分类，帮助用户保持文件系统整洁有序。

## 行为准则
1. 优先处理重要文件（如文档、工作文件）
2. 删除重复文件前征得用户同意
3. 保持目录结构清晰，层级不超过 3 层
4. 定期清理临时文件

## 能力范围
- 文件扫描与分类
- 批量重命名和移动
- 检测重复文件
- 生成整理报告

## 限制
- 仅能操作用户授权的目录
- 不删除系统文件
- 不访问网络（除非用户明确要求）

7.2.2 记忆管理（MEMORY.md）

## 用户偏好
用户喜欢将文档按项目分类，每个项目一个文件夹，文件夹内按"文档"、"图片"、"素材"子目录分类。

## 重要信息
- 主要工作项目：AI 助手开发、文档自动化
- 重要联系人：[email protected], [email protected]
- 偏好模型：Claude Sonnet 4（长上下文）、GPT-4o（多模态）

## 历史上下文
- 最近关注的文件：~/projects/ai-assistant/README.md
- 最近整理的目录：~/Downloads/2026-03
- 最后生成的报告：Documents/周报 -2026-03-10.docx

7.3 Webhook 集成

7.3.1 配置 Webhook

# 添加 Webhook
openclaw webhooks add \
  --url"https://your-server.com/webhook" \
  --secret"your-webhook-secret" \
  --events"message,agent_task_completed"

# 列出 Webhook
openclaw webhooks list

# 删除 Webhook
openclaw webhooks delete --id webhook-id

7.3.2 Webhook 接收示例

Node.js 示例：

const express = require('express');
const crypto = require('crypto');
const app = express();
const WEBHOOK_SECRET = 'your-webhook-secret';

// 验证 Webhook 签名
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-openclaw-signature'];
  const payload = JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(403).json({ error: 'Invalid signature' });
  }

  // 处理事件
  switch (req.body.event) {
    case 'message':
      console.log('收到消息:', req.body.message);
      break;
    case 'agent_task_completed':
      console.log('任务完成:', req.body.task);
      break;
  }

  res.json({ success: true });
});

app.listen(3000, () => {
  console.log('Webhook 服务运行在端口 3000');
});

7.4 Docker 生产部署

7.4.1 Docker Compose 配置

生产环境配置文件（docker-compose.prod.yml）：

version:'3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw-prod
    restart: unless-stopped
    # 端口映射
    ports:
      -"18789:18789"
      -"3000:3000"
    # 数据卷
    volumes:
      - ~/.openclaw:/root/.openclaw
      - openclaw-data:/var/lib/openclaw
    # 环境变量
    environment:
      - NODE_ENV=production
      - TZ=Asia/Shanghai
      - LOG_LEVEL=info
    # 资源限制
    deploy:
      resources:
        limits:
          cpus:'2'
          memory: 4G
        reservations:
          cpus:'1'
          memory: 2G
    # 健康检查
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
      interval: 30s
      timeout: 10s
      retries: 3
    # 日志配置
    logging:
      driver:"json-file"
      options:
        max-size:"10m"
        max-file:"3"
volumes:
  openclaw-data:
    driver: local

7.4.2 部署命令

# 使用生产配置启动
docker-compose -f docker-compose.prod.yml up -d

# 查看日志
docker-compose -f docker-compose.prod.yml logs -f

# 扩容到 3 个实例
docker-compose -f docker-compose.prod.yml up -d --scale openclaw=3

# 滚动更新（零停机）
docker-compose -f docker-compose.prod.yml up -d --no-deps --build

7.4.3 Nginx 反向代理

Nginx 配置（/etc/nginx/conf.d/openclaw.conf）：

upstream openclaw {
  least_conn;
  server localhost:18789;
  server localhost:18790;
  server localhost:18791;
}

server {
  listen 80;
  server_name your-domain.com;
  client_max_body_size 10M;

  location / {
    proxy_pass http://openclaw;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
  }

  location /ws {
    proxy_pass http://openclaw;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
  }
}

重启 Nginx：

# 测试配置
sudo nginx -t

# 重启服务
sudo systemctl restart nginx

八、总结与进阶方向

8.1 核心要点回顾

今天，我们从理论到实践，全面掌握了 OpenClaw 的安装、配置、使用和开发。

关键收获：

1. 从零到一的完整部署流程
2. 核心功能的实际应用能力
3. 两个完整的实战案例
4. 常见问题的快速解决方法
5. 进阶应用和自定义开发路径

8.2 进阶学习方向

8.2.1 多 Agent 协作

场景：复杂任务需要多个 Agent 协同

配置示例：

agents:
  collaboration:
    enabled: true
    roles:
      - name: "文档分析师"
        capabilities: ["文件分析", "数据提取"]
        model: "claude-3-5-sonnet"
      - name: "报告生成器"
        capabilities: ["模板渲染", "内容生成"]
        model: "gpt-4o"
      - name: "质量审核员"
        capabilities: ["规则检查", "内容审核"]
        model: "claude-3-5-sonnet"

协作协议（ACP）：

// Agent 间通信协议
interface AgentMessage {
  from: string;       # 发送者 Agent ID
  to: string;         # 接收者 Agent ID
  content: string;    # 消息内容
  context: any;       # 上下文信息
  timestamp: number;  # 时间戳
}

// 发送消息到其他 Agent
async function sendToAgent(to: string, content: string, context: any) {
  const message: AgentMessage = {
    from: 'document-analyst',
    to,
    content,
    context,
    timestamp: Date.now()
  };
  await AgentRouter.send(message);
}

8.2.2 RAG 知识库集成

场景：企业私有知识库查询

集成方案：

// 知识库检索 Skill
import { VectorDB } from '@openclaw/memory';

export default async function queryKnowledgeBase(query: string) {
  // 1. 向量化查询
  const queryVector = await LLM.embed(query);
  const results = await VectorDB.search({
    vector: queryVector,
    topK: 5,
    threshold: 0.7
  });

  // 2. 混合检索（向量 + 全文）
  const fullTextResults = await fullTextSearch(query);

  // 3. Rerank（重新排序）
  const reranked = await rerank(results, fullTextResults, query);

  return {
    sources: reranked,
    answer: await LLM.generateWithSources(query, reranked)
  };
}

8.2.3 多模态能力扩展

场景：同时处理文本、图像、音频

多模态 Skill 示例：

export default async function processMultiModal(args: any) {
  const { text, image, audio } = args;

  // 1. 分析每种模态
  const textAnalysis = await LLM.analyze(text);
  const imageAnalysis = await VisionModel.analyze(image);
  const audioTranscript = await ASRModel.transcribe(audio);

  // 2. 融合多模态信息
  const fused = await LLM.fuse({
    text: textAnalysis,
    image: imageAnalysis,
    audio: audioTranscript
  });

  // 3. 生成综合响应
  return {
    success: true,
    fused_result: fused
  };
}

8.2.4 工作流编排

场景：复杂多步骤任务自动化

工作流定义：

workflows:
  weekly-report:
    name: "周报生成工作流"
    steps:
      - name: "收集数据"
        agent: "data-collector"
        action: "gather_weekly_data"
      - name: "分析数据"
        agent: "analyst"
        action: "analyze_metrics"
      - name: "生成报告"
        agent: "reporter"
        action: "generate_weekly_report"
      - name: "发送邮件"
        agent: "notifier"
        action: "send_email"
    triggers:
      - cron: "0 17 * * 5" # 每周五 17 点

工作流执行：

export default async function executeWorkflow(workflowName: string) {
  const workflow = getWorkflow(workflowName);
  for (const step of workflow.steps) {
    console.log(`执行步骤：${step.name}`);
    // 执行步骤
    const result = await executeAgentAction(step);
    // 传递上下文到下一步
    step.context = result.context;
    console.log(`步骤完成：${step.name}`);
  }
  return {
    success: true,
    workflow: workflowName,
    steps_completed: workflow.steps.length
  };
}

8.3 学习资源推荐

8.3.1 官方资源

官方文档：https://docs.openclaw.ai

GitHub 仓库：https://github.com/openclaw/openclaw

OpenClaw Hub（技能市场）：https://clawhub.org

8.3.2 社区资源

中文社区：关注官方 GitHub Discussions

学习平台：参与开源贡献

8.3.3 进阶书籍推荐

AI 智能体：《人工智能：一种现代方法》- Stuart Russell & Peter Norvig

系统架构：《Designing Data-Intensive Applications》- Nathan Marz

开源开发：《Pro Git》- Scott Chacon & Ben Straub

8.4 实践建议

8.4.1 循序渐进学习路径

初级阶段（1-2 周）：

• 完成 OpenClaw 安装和配置
• 连接至少 1 个通讯平台
• 掌握基础 CLI 命令使用
• 完成第一个简单自动化任务

中级阶段（3-4 周）：

• 开发第一个自定义 Skill
• 配置本地模型（Ollama）
• 实现定时任务自动化
• 理解记忆系统和向量检索

高级阶段（1-2 个月）：

• 开发多个 Agent 并实现协作
• 集成 RAG 知识库
• Docker 生产环境部署
• Webhook 和企业级集成

8.4.2 持续学习建议

1. 关注官方动态：

   • 定期查看 GitHub Releases
   • 订阅官方博客更新
   • 参与社区讨论

2. 动手实践：

   • 从小任务开始，逐步增加复杂度
   • 每个阶段都有可运行的 Demo
   • 记录问题和解决过程

3. 分享经验：

   • 在社区分享你的 Skill 和经验
   • 帮助新手解决常见问题
   • 参与开源贡献

4. 安全第一：

   • 始终注意权限控制
   • 保护 API Key 和敏感信息
   • 定期审计操作日志

---

OpenClaw 代表了 AI 发展的一个重要方向：从"对话智能"走向"行动智能"。它不仅是一个工具，更是一个能够理解你、学习你、帮你干活的"数字员工"。通过今天的学习，你已经掌握了核心功能。但更重要的是，这只是开始。OpenClaw 的强大在于其可扩展性——社区贡献的 Skills、你未来可能开发的自定义技能，都会让这个平台越来越强大。**现在，就开始动手实践吧！**从简单的文件整理开始，逐步探索更复杂的应用场景。在实践中你会遇到问题，也会发现新的可能性。记住，OpenClaw 的本质是帮助你更高效地完成工作，而不是取代你。真正有价值的，是你用这个工具创造的成果。