AI创想

标题: OpenClaw 从入门到精通 [打印本页]

---

作者: 米落枫    时间: 昨天 14:24
标题: OpenClaw 从入门到精通
作者：MtoSlc
第1章 认识 OpenClaw

用一句话解释：OpenClaw 是一个跑在你自己电脑或服务器上的私人 AI 助手。
你可以把它想象成一个"24小时在线的私人管家"——它不住在云端（不像 ChatGPT 网站），而是住在你自己的机器里，听你的话，按你的方式工作。
它不是一个聊天网站，而是一个你可以自由控制、自由扩展、自由连接的 AI 平台。你可以让它：

在 Telegram/Discord/WhatsApp 上陪你聊天
帮你管理邮件、日历
自动执行代码、操作文件
监控服务器、发告警通知
甚至控制智能家居设备

1.2 发展历程

OpenClaw 不是一天诞生的，它经历了三个重要阶段：

时间	名称	定位
2024年	Clawdbot（龙虾机器人）	简单的聊天机器人
2025年	Moltbot	升级为编码助手
2026年	OpenClaw	完整的自主 AI Agent 平台

为什么叫 "Claw"（爪子）？
名字来源于它的前身 Clawdbot（Claw + Bot = 爪子机器人）。"Claw" 代表龙虾的爪子——看起来小，但功能强大。OpenClaw 的 logo 也是一只龙虾，这已经成为了社区的标志性符号。
社区热度：在 GitHub 上仅用 5 个月就获得了 355,000+ 颗星（Stars），成为 2026 年最热门的开源 AI 项目之一。
1.3 能做什么

OpenClaw 的能力可以分为几个层次：
基础能力（聊天交互）

在任何聊天软件上和你对话
记住你的偏好和历史对话
理解上下文，给出连贯的回答

进阶能力（工具使用）

读写你电脑上的文件
执行 Shell 命令
搜索互联网获取实时信息
操作浏览器自动化任务

高级能力（自动化）

定时执行任务（比如每天早上发天气预报）
监控网站变化并通知你
管理你的邮件收件箱
自动回复重复性消息
代码审查和自动修复

终极能力（自主 Agent）

独立做出决策并执行
同时管理多个频道和用户
与其他 AI Agent 协作完成任务

1.4 与 ChatGPT/Claude 网页版的区别

对比维度	ChatGPT/Claude 网页版	OpenClaw
运行位置	云端服务器	你自己的机器
数据隐私	数据经过对方服务器	数据留在本地
持续运行	打开网页才能用	24小时后台运行
主动执行	只能等你提问	可以主动执行任务
扩展能力	有限的插件	无限扩展（Skills + Plugins）
多渠道	只能用它的界面	Telegram/Discord/WhatsApp/Slack 等
费用	按月订阅费	免费开源，只需支付模型 API 费用
控制权	平台说了算	你说了算

简单类比：

ChatGPT 网页版 = 租公寓（方便但不完全属于你）
OpenClaw = 自己建房（需要动手但完全由你掌控）

1.5 核心优势

隐私保护：所有数据在你自己的机器上处理，不经过第三方
完全自主：想加什么功能就加什么，没有任何限制
多渠道接入：一个 Agent 连接所有聊天软件，统一管理
开源免费：代码完全开放，社区活跃，更新快速
可扩展性强：Skills 系统让它能"学会"无限新能力
24小时运行：作为后台服务持续工作，不需要你守着网页

第2章 安装与快速上手

2.1 环境要求

在开始安装之前，确认你的环境满足以下要求：
操作系统

Windows 10/11（推荐）
macOS 12+
Linux（Ubuntu 20.04+ / Debian 11+）

必备软件

Node.js 18 或更高版本（运行 OpenClaw 的必备环境）
npm（Node.js 的包管理器，随 Node.js 一起安装）

网络要求

稳定的互联网连接
能访问你选择的 AI 模型 API（如 Anthropic、OpenAI）

验证环境：

1. # 检查 Node.js 版本（需要 18+）
2. node --version
4. # 检查 npm 版本
5. npm --version

复制代码

如果输出了版本号（比如 v20.11.0），说明环境没问题。如果提示 "node is not recognized"，需要先安装 Node.js。
2.2 安装步骤

OpenClaw 有多种安装方式，推荐新手使用 npm 安装。
方式一：npm 安装（推荐）

1. # 全局安装 OpenClaw
2. npm install -g openclaw
4. # 验证安装成功
5. openclaw --version

复制代码

方式二：从源码安装

1. # 克隆官方仓库
2. git clone https://github.com/openclaw/openclaw.git
4. # 进入目录
5. cd openclaw
7. # 安装依赖
8. npm install
10. # 全局链接（可选）
11. npm link

复制代码

方式三：Docker 安装

1. # 拉取官方镜像
2. docker pull openclaw/openclaw:latest
4. # 运行容器
5. docker run -d \
6.   --name openclaw \
7.   -p 18789:18789 \
8.   -v ~/.openclaw:/root/.openclaw \
9.   openclaw/openclaw:latest

复制代码

三种方式对比：

方式	难度	推荐场景
npm 安装	简单	大多数用户，推荐新手使用
源码安装	中等	需要修改源码或参与开发
Docker 安装	中等	服务器部署、隔离环境

2.3 配置向导 onboard

安装完成后，第一步是运行配置向导。这个向导会一步步引导你完成初始设置。

1. # 启动交互式配置向导
2. openclaw onboard

复制代码

向导会依次问你以下问题：

选择 AI 模型：你想用哪个模型？（Claude、GPT-4、Gemini 等）
输入 API Key：你的模型 API 密钥是什么？
选择频道：想连接哪个聊天平台？（Telegram、Discord 等）
设置工作空间：Agent 可以访问哪些目录？
安装守护进程：是否设为开机自启？

一键完成所有设置（含后台服务安装）：

1. openclaw onboard --install-daemon

复制代码

配置完成后，生成的文件：

~/.openclaw/openclaw.json — 主配置文件
~/.openclaw/agents/default/ — 默认 Agent 目录
~/.openclaw/agents/default/SOUL.md — Agent 灵魂文件
~/.openclaw/agents/default/AGENTS.md — 行为规则文件

2.4 连接第一个频道

频道（Channel）是你和 Agent 对话的桥梁。这里以 Telegram 为例，因为它最容易设置。
连接 Telegram

第一步：获取 Telegram Bot Token

在 Telegram 中搜索 @BotFather
发送 /newbot 命令
按提示设置机器人名称
复制获得的 Token（格式类似 123456789:ABCdefGHIjklMNOpqrSTUvwxYZ）

第二步：配置 Telegram 频道
方法一：在 onboard 向导中直接选择 Telegram 并粘贴 Token
方法二：手动编辑 openclaw.json，添加：

1. {
2.   "channels": {
3.     "telegram": {
4.       "enabled": true,
5.       "botToken": "你的BOT_TOKEN"
6.     }
7.   }
8. }

复制代码

第三步：测试连接

1. # 检查频道状态
2. openclaw channels status --probe

复制代码

如果显示 Telegram 连接正常，说明成功了！
连接 Discord（备选）

Discord 连接需要创建一个 Discord Application：

访问 https://discord.com/developers/applications
创建新应用 → Bot → 复制 Token
在 openclaw.json 中配置：

1. {
2.   "channels": {
3.     "discord": {
4.       "enabled": true,
5.       "botToken": "你的DISCORD_BOT_TOKEN"
6.     }
7.   }
8. }

复制代码

2.5 启动与验证

启动 Gateway

Gateway 是 OpenClaw 的核心服务，负责管理所有连接。

1. # 方式一：后台启动（推荐）
2. openclaw gateway start
4. # 方式二：前台启动（调试用，可以看到实时日志）
5. openclaw gateway run

复制代码

验证安装

1. # 检查 Gateway 状态
2. openclaw gateway status
4. # 检查模型连接
5. openclaw models status --probe
7. # 检查频道连接
8. openclaw channels status --probe
10. # 整体健康检查
11. openclaw status
13. # 查看实时日志
14. openclaw logs --follow

复制代码

成功的标志：

openclaw gateway status 显示服务正在运行
你在 Telegram/Discord 给机器人发消息，能收到回复
openclaw logs --follow 显示请求被正常处理

2.6 常见问题排错

问题 1：openclaw 命令找不到

原因：npm 全局安装路径未加入 PATH
解决：

1. # Windows PowerShell
2. $env:PATH += ";$(npm config get prefix)"
4. # 永久解决：将 npm prefix 路径加入系统环境变量 PATH
5. npm config get prefix
6. # 把输出的路径加入系统 PATH 环境变量

复制代码

问题 2：Gateway 启动后立即退出

原因：端口被占用或配置有误
解决：

1. # 用 doctor 命令诊断
2. openclaw doctor
4. # 前台启动查看错误信息
5. openclaw gateway run
7. # 检查端口是否被占用
8. netstat -ano | findstr 18789

复制代码

问题 3：频道连接失败

原因：Token 错误或网络不通
解决：

1. # 检查配置是否正确
2. openclaw config get channels
4. # 重新运行配置向导
5. openclaw configure
7. # 检查网络连通性
8. curl -v https://api.telegram.org

复制代码

问题 4：模型 API 调用失败

原因：API Key 无效或余额不足
解决：

1. # 检查模型状态
2. openclaw models status
4. # 重新设置 API Key
5. openclaw config set model.apiKey "你的新KEY"

复制代码

第3章 核心概念拆解

3.1 Gateway 网关

一句话解释：Gateway 是 OpenClaw 的中央大脑，一切请求都经过它。
它负责：

接收来自各个频道（Telegram、Discord 等）的消息
调用 AI 模型（Claude、GPT 等）生成回复
管理 Tools 和 Skills 的调用
将回复发送回正确的频道

类比理解：Gateway 就像一家公司的前台接待员 + 调度中心——所有来电（消息）先到它这里，它决定谁来处理、怎么回复。
[用户发消息] → [频道] → [Gateway] → [AI 模型] → [执行工具] → [回复用户]3.2 Channels 频道

一句话解释：Channel 是你和 Agent 对话的通道，就是各种聊天软件。
支持的频道：

频道	设置难度	适合场景
Telegram	简单	个人使用，最推荐
Discord	简单	团队协作，社区场景
WhatsApp	中等	日常通讯
Slack	中等	工作环境
Signal	中等	注重隐私
iMessage	较难	Apple 生态

类比理解：Channel 就像公司的电话线——不同的客户用不同的方式联系公司（打电话、发邮件、发消息），Gateway 负责统一接收。
3.3 Tools 工具

一句话解释：Tool 是 Agent 的手，没有工具，Agent 只能空谈，什么都做不了。
内置工具（约 26 个）：

工具	功能	类比
read	读取文件内容	打开文件看
write	写入新文件	新建文件写内容
edit	编辑已有文件	修改文件内容
exec	执行 Shell 命令	打开终端输入命令
fetch	获取网页内容	打开浏览器看网页
browser	控制浏览器	操作 Chrome 浏览器
search	搜索互联网	用 Google 搜索

关键理解：

Tools 是原子操作，每个工具只做一件事
没有 Tool enabled，Agent 就像没有手的人——知道怎么做但做不到
工具可以被启用或禁用（出于安全考虑）

3.4 Skills 技能

一句话解释：Skill 是 Agent 的课本，教 Agent 何时、如何使用工具来完成复杂任务。
关键特征：

Skills 是 Markdown 文件（通常叫 SKILL.md）
里面写的是 SOP（标准操作流程），告诉 Agent 怎么做
一个 Skill 可以组合多个 Tool
OpenClaw 有 53+ 官方技能可通过 ClawHub 安装

类比理解：

如果 Tools 是手，那 Skills 就是菜谱
手会切菜、会开火，但需要菜谱告诉你"先做什么、后做什么"
有了菜谱（Skill），普通人也能做出一道复杂的菜

Skill 文件示例：

1. # 代码审查技能
3. ## 何时使用
4. 当用户发送代码或要求审查代码时
6. ## 执行步骤
7. 1. 使用 `read` 工具读取代码文件
8. 2. 分析代码结构、命名、逻辑
9. 3. 指出潜在问题和安全风险
10. 4. 使用 `edit` 工具给出修改建议
11. 5. 输出审查报告

复制代码

3.5 Hands 手

一句话解释：Hands 是 7 个内置的自主能力模块，让 Agent 能独立工作。
每个 Hand 负责一类特定能力，比如：

文件操作 Hand
网络通信 Hand
代码执行 Hand
浏览器自动化 Hand
等等

Hands 和 Tools 的关系：

Hands 是能力分类（大模块）
Tools 是具体操作（小动作）
一个 Hand 包含多个 Tool

3.6 Plugins 插件

一句话解释：Plugin 是超能力扩展包，可以给 OpenClaw 增加全新的频道、工具、内存后端等。
插件能做什么：

添加新的频道类型（比如微信、企业微信）
添加新的工具（比如控制智能家居）
添加新的存储后端（比如用 Redis 代替本地文件存记忆）
添加新的认证方式

类比理解：

如果 OpenClaw 是一部手机，Plugins 就是APP
手机本身功能有限，装上 APP 后才变得无所不能

3.7 一张图看懂全流程

当你在 Telegram 上给 OpenClaw 发消息 "帮我查一下今天北京的天气" 时，整个流程是这样的：

1. ┌──────────────┐
2. │ 你在 Telegram │  ← 第1步：你发送消息
3. │ 发送消息      │
4. └──────┬───────┘
5.        │
6.        ▼
7. ┌──────────────┐
8. │  Channel     │  ← 第2步：Telegram 频道接收消息，转发给 Gateway
9. │  (Telegram)  │
10. └──────┬───────┘
11.        │
12.        ▼
13. ┌──────────────┐
14. │   Gateway    │  ← 第3步：Gateway 收到消息，组装系统提示词
15. │  (中央大脑)   │     注入 SOUL.md + AGENTS.md + 相关 Skills
16. └──────┬───────┘
17.        │
18.        ▼
19. ┌──────────────┐
20. │  AI 模型      │  ← 第4步：Claude/GPT 分析消息，决定调用哪个 Skill
21. │  (Claude等)   │     Skill 指导使用哪些 Tools
22. └──────┬───────┘
23.        │
24.        ▼
25. ┌──────────────┐
26. │   Tools      │  ← 第5步：执行具体工具
27. │  (搜索+读取)  │     fetch 搜索天气 → 整理结果
28. └──────┬───────┘
29.        │
30.        ▼
31. ┌──────────────┐
32. │  Gateway     │  ← 第6步：Gateway 把结果发回 Telegram
33. └──────┬───────┘
34.        │
35.        ▼
36. ┌──────────────┐
37. │ 你在 Telegram │  ← 第7步：你收到天气回复！
38. │ 收到回复      │
39. └──────────────┘

复制代码

核心要点：

消息从 频道 进入
Gateway 调度一切
AI 模型 理解意图
Skills 指导策略
Tools 执行动作
结果通过 频道 返回

---

第4章 配置文件详解

4.1 openclaw.json 核心结构

openclaw.json 是 OpenClaw 的核心配置文件，所有设置都在这里。它通常位于 ~/.openclaw/openclaw.json。
配置文件位置查看命令：

1. # 查看配置文件路径
2. openclaw config file

复制代码

最简配置示例：

1. {
2.   "agents": {
3.     "default": {
4.       "model": {
5.         "provider": "anthropic",
6.         "apiKey": "sk-ant-xxxxxxxxxxxx",
7.         "model": "claude-sonnet-4-6"
8.       },
9.       "channels": ["telegram"],
10.       "workspace": "/path/to/workspace"
11.     }
12.   },
13.   "channels": {
14.     "telegram": {
15.       "enabled": true,
16.       "botToken": "123456:ABC-DEF"
17.     }
18.   }
19. }

复制代码

结构解读：

agents — Agent 定义（可以有多个）

default — Agent 名称

model — AI 模型配置
channels — 启用的频道列表
workspace — 工作空间路径



channels — 频道详细配置

4.2 Agent 配置

每个 Agent 是独立的 AI 实体，有自己的模型、频道、工作空间和人格。
完整 Agent 配置：

1. {
2.   "agents": {
3.     "my-assistant": {
4.       "model": {
5.         "provider": "anthropic",
6.         "apiKey": "sk-ant-xxxxxxxxxxxx",
7.         "model": "claude-sonnet-4-6"
8.       },
9.       "channels": ["telegram", "discord"],
10.       "workspace": "/home/user/openclaw/workspace/my-assistant",
11.       "name": "小助手",
12.       "systemPrompt": "你是一个有用的AI助手",
13.       "tools": {
14.         "exec": true,
15.         "browser": false
16.       },
17.       "skills": {
18.         "allowed": ["weather", "email", "calendar"]
19.       }
20.     }
21.   }
22. }

复制代码

支持的模型供应商（provider）：

provider	对应模型	示例 model 值
anthropic	Claude	claude-sonnet-4-6, claude-opus-4-7
openai	GPT	gpt-4o, gpt-4o-mini
google	Gemini	gemini-2.0-flash
openrouter	多模型聚合	任意 OpenRouter 模型

切换模型的操作：

1. # 查看可用模型列表
2. openclaw models list
4. # 检查当前模型状态
5. openclaw models status
7. # 切换模型（修改配置）
8. openclaw config set agents.default.model.model "claude-opus-4-7"
9. openclaw config set agents.default.model.provider "anthropic"
11. # 重启 Gateway 使配置生效
12. openclaw gateway restart

复制代码

4.3 频道配置

频道在 channels 字段下配置，每个频道有自己的参数。
Telegram 频道配置：

1. {
2.   "channels": {
3.     "telegram": {
4.       "enabled": true,
5.       "botToken": "你的BOT_TOKEN",
6.       "allowedUsers": ["你的Telegram_ID"],
7.       "commands": {
8.         "reset": true,
9.         "help": true
10.       }
11.     }
12.   }
13. }

复制代码

Discord 频道配置：

1. {
2.   "channels": {
3.     "discord": {
4.       "enabled": true,
5.       "botToken": "你的DISCORD_BOT_TOKEN",
6.       "allowedGuilds": ["服务器ID"],
7.       "allowedChannels": ["频道ID"]
8.     }
9.   }
10. }

复制代码

WhatsApp 频道配置：

1. {
2.   "channels": {
3.     "whatsapp": {
4.       "enabled": true,
5.       "phoneNumberId": "你的PHONE_NUMBER_ID",
6.       "accessToken": "你的ACCESS_TOKEN"
7.     }
8.   }
9. }

复制代码

频道操作命令：

1. # 查看所有频道状态
2. openclaw channels status
4. # 探测实时连接
5. openclaw channels status --probe
7. # 列出某个频道的配对信息
8. openclaw pairing list telegram
10. # 批准一个配对码
11. openclaw pairing approve <code>

复制代码

4.4 工具配置

工具配置控制 Agent 可以使用哪些 Tools。
在 Agent 级别配置工具：

1. {
2.   "agents": {
3.     "default": {
4.       "tools": {
5.         "read": true,
6.         "write": true,
7.         "edit": true,
8.         "exec": true,
9.         "fetch": true,
10.         "browser": false,
11.         "search": true
12.       }
13.     }
14.   }
15. }

复制代码

全局工具策略配置：

1. {
2.   "tools": {
3.     "exec": {
4.       "policy": "ask",
5.       "allowedCommands": ["ls", "cat", "grep"],
6.       "deniedCommands": ["rm -rf", "sudo"]
7.     },
8.     "browser": {
9.       "policy": "disabled"
10.     }
11.   }
12. }

复制代码

工具策略说明：

策略值	含义
allow	允许直接使用
ask	需要用户确认后才能执行
deny	禁止使用

4.5 MCP 服务器配置

MCP（Model Context Protocol）服务器让 OpenClaw 能连接外部服务和 API。
配置示例：

1. {
2.   "mcp": {
3.     "servers": {
4.       "filesystem": {
5.         "command": "npx",
6.         "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
7.       },
8.       "github": {
9.         "command": "npx",
10.         "args": ["-y", "@modelcontextprotocol/server-github"],
11.         "env": {
12.           "GITHUB_TOKEN": "你的GITHUB_TOKEN"
13.         }
14.       }
15.     }
16.   }
17. }

复制代码

关键理解：

所有 MCP 服务器配置集中在 openclaw.json 的 mcp.servers 下
Gateway 上的所有 Agent 都能使用这些 MCP 工具
MCP 服务器以独立进程运行，通过 stdio 与 Gateway 通信

4.6 工作空间 Workspace

一句话解释：Workspace 是 Agent 可以访问的文件系统边界，是安全的第一道防线。
配置方式：

1. {
2.   "agents": {
3.     "default": {
4.       "workspace": "/home/user/openclaw/workspace/default"
5.     }
6.   }
7. }

复制代码

工作空间规则：

Agent 只能访问 workspace 内的文件
超出 workspace 范围的文件操作会被拒绝
每个 Agent 可以有独立的 workspace
默认 workspace：<OPENCLAW_WORKSPACE_ROOT>/agents/<agent-name>/

检查当前 workspace：

1. openclaw config get agents.default.workspace

复制代码

4.7 多 Agent 配置

一个 Gateway 可以管理多个 Agent，每个 Agent 独立运行。
多 Agent 配置示例：

1. {
2.   "agents": {
3.     "assistant": {
4.       "model": {
5.         "provider": "anthropic",
6.         "apiKey": "sk-ant-xxxx",
7.         "model": "claude-sonnet-4-6"
8.       },
9.       "channels": ["telegram"],
10.       "workspace": "/workspace/assistant"
11.     },
12.     "coder": {
13.       "model": {
14.         "provider": "anthropic",
15.         "apiKey": "sk-ant-xxxx",
16.         "model": "claude-sonnet-4-6"
17.       },
18.       "channels": ["discord"],
19.       "workspace": "/workspace/coder"
20.     },
21.     "researcher": {
22.       "model": {
23.         "provider": "openai",
24.         "apiKey": "sk-xxxx",
25.         "model": "gpt-4o"
26.       },
27.       "channels": ["slack"],
28.       "workspace": "/workspace/researcher"
29.     }
30.   }
31. }

复制代码

多 Agent 操作命令：

1. # 查看所有 Agent
2. openclaw agent list
4. # 针对特定 Agent 执行命令
5. openclaw agent --name coder status
7. # 汇总所有 Agent 的配置
8. openclaw status --all-agents

复制代码

全局参数：

1. # --all-agents：汇总所有已配置的 Agent
2. openclaw models status --all-agents

复制代码

第5章 Agent 人格定制


原文地址：https://blog.csdn.net/lsgzn/article/details/160855452

---

欢迎光临 AI创想 (https://llms-ai.com/)

Powered by Discuz! X3.4