OpenClaw 从入门到精通

米落枫 · 发表于昨天 14:24

作者：MtoSlc
第1章认识 OpenClaw

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

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 的能力可以分为几个层次：
基础能力（聊天交互）

进阶能力（工具使用）

高级能力（自动化）

终极能力（自主 Agent）

1.4 与 ChatGPT/Claude 网页版的区别

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

简单类比：

1.5 核心优势

隐私保护

完全自主

多渠道接入

开源免费

可扩展性强

24小时运行

第2章安装与快速上手

2.1 环境要求

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

必备软件

Node.js

npm

网络要求

验证环境：

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

复制代码

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

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

# 全局安装 OpenClaw
npm install -g openclaw
# 验证安装成功
openclaw --version

复制代码

方式二：从源码安装

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

复制代码

方式三：Docker 安装

# 拉取官方镜像
docker pull openclaw/openclaw:latest
# 运行容器
docker run -d \
--name openclaw \
-p 18789:18789 \
-v ~/.openclaw:/root/.openclaw \
openclaw/openclaw:latest

复制代码

三种方式对比：

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

2.3 配置向导 onboard

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

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

复制代码

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

选择 AI 模型

输入 API Key

选择频道

设置工作空间

安装守护进程

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

openclaw onboard --install-daemon

复制代码

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

2.4 连接第一个频道

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

第一步：获取 Telegram Bot Token

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

{
"channels": {
"telegram": {
"enabled": true,
"botToken": "你的BOT_TOKEN"
}
}
}

复制代码

第三步：测试连接

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

复制代码

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

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

{
"channels": {
"discord": {
"enabled": true,
"botToken": "你的DISCORD_BOT_TOKEN"
}
}
}

复制代码

2.5 启动与验证

启动 Gateway

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

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

复制代码

验证安装

# 检查 Gateway 状态
openclaw gateway status
# 检查模型连接
openclaw models status --probe
# 检查频道连接
openclaw channels status --probe
# 整体健康检查
openclaw status
# 查看实时日志
openclaw logs --follow

复制代码

成功的标志：

2.6 常见问题排错

问题 1：openclaw 命令找不到

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

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

复制代码

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

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

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

复制代码

问题 3：频道连接失败

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

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

复制代码

问题 4：模型 API 调用失败

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

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

复制代码

第3章核心概念拆解

3.1 Gateway 网关

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

类比理解：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 搜索

关键理解：

原子操作

3.4 Skills 技能

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

Markdown 文件

类比理解：

菜谱

Skill 文件示例：

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

复制代码

3.5 Hands 手

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

Hands 和 Tools 的关系：

能力分类

具体操作

3.6 Plugins 插件

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

类比理解：

APP

3.7 一张图看懂全流程

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

┌──────────────┐
│ 你在 Telegram │ ← 第1步：你发送消息
│ 发送消息 │
└──────┬───────┘
│
▼
┌──────────────┐
│ Channel │ ← 第2步：Telegram 频道接收消息，转发给 Gateway
│ (Telegram) │
└──────┬───────┘
│
▼
┌──────────────┐
│ Gateway │ ← 第3步：Gateway 收到消息，组装系统提示词
│ (中央大脑) │ 注入 SOUL.md + AGENTS.md + 相关 Skills
└──────┬───────┘
│
▼
┌──────────────┐
│ AI 模型 │ ← 第4步：Claude/GPT 分析消息，决定调用哪个 Skill
│ (Claude等) │ Skill 指导使用哪些 Tools
└──────┬───────┘
│
▼
┌──────────────┐
│ Tools │ ← 第5步：执行具体工具
│ (搜索+读取) │ fetch 搜索天气 → 整理结果
└──────┬───────┘
│
▼
┌──────────────┐
│ Gateway │ ← 第6步：Gateway 把结果发回 Telegram
└──────┬───────┘
│
▼
┌──────────────┐
│ 你在 Telegram │ ← 第7步：你收到天气回复！
│ 收到回复 │
└──────────────┘

复制代码

核心要点：

频道

Gateway

AI 模型

Skills

Tools

频道

第4章配置文件详解

4.1 openclaw.json 核心结构

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

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

复制代码

最简配置示例：

{
"agents": {
"default": {
"model": {
"provider": "anthropic",
"apiKey": "sk-ant-xxxxxxxxxxxx",
"model": "claude-sonnet-4-6"
},
"channels": ["telegram"],
"workspace": "/path/to/workspace"
}
},
"channels": {
"telegram": {
"enabled": true,
"botToken": "123456:ABC-DEF"
}
}
}

复制代码

结构解读：

4.2 Agent 配置

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

{
"agents": {
"my-assistant": {
"model": {
"provider": "anthropic",
"apiKey": "sk-ant-xxxxxxxxxxxx",
"model": "claude-sonnet-4-6"
},
"channels": ["telegram", "discord"],
"workspace": "/home/user/openclaw/workspace/my-assistant",
"name": "小助手",
"systemPrompt": "你是一个有用的AI助手",
"tools": {
"exec": true,
"browser": false
},
"skills": {
"allowed": ["weather", "email", "calendar"]
}
}
}
}

复制代码

支持的模型供应商（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 模型

切换模型的操作：

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

复制代码

4.3 频道配置

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

{
"channels": {
"telegram": {
"enabled": true,
"botToken": "你的BOT_TOKEN",
"allowedUsers": ["你的Telegram_ID"],
"commands": {
"reset": true,
"help": true
}
}
}
}

复制代码

Discord 频道配置：

{
"channels": {
"discord": {
"enabled": true,
"botToken": "你的DISCORD_BOT_TOKEN",
"allowedGuilds": ["服务器ID"],
"allowedChannels": ["频道ID"]
}
}
}

复制代码

WhatsApp 频道配置：

{
"channels": {
"whatsapp": {
"enabled": true,
"phoneNumberId": "你的PHONE_NUMBER_ID",
"accessToken": "你的ACCESS_TOKEN"
}
}
}

复制代码

频道操作命令：

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

复制代码

4.4 工具配置

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

{
"agents": {
"default": {
"tools": {
"read": true,
"write": true,
"edit": true,
"exec": true,
"fetch": true,
"browser": false,
"search": true
}
}
}
}

复制代码

全局工具策略配置：

{
"tools": {
"exec": {
"policy": "ask",
"allowedCommands": ["ls", "cat", "grep"],
"deniedCommands": ["rm -rf", "sudo"]
},
"browser": {
"policy": "disabled"
}
}
}

复制代码

工具策略说明：

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

4.5 MCP 服务器配置

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

{
"mcp": {
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "你的GITHUB_TOKEN"
}
}
}
}
}

复制代码

关键理解：

所有 Agent

4.6 工作空间 Workspace

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

{
"agents": {
"default": {
"workspace": "/home/user/openclaw/workspace/default"
}
}
}

复制代码

工作空间规则：

只能

检查当前 workspace：

openclaw config get agents.default.workspace

复制代码

4.7 多 Agent 配置

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

{
"agents": {
"assistant": {
"model": {
"provider": "anthropic",
"apiKey": "sk-ant-xxxx",
"model": "claude-sonnet-4-6"
},
"channels": ["telegram"],
"workspace": "/workspace/assistant"
},
"coder": {
"model": {
"provider": "anthropic",
"apiKey": "sk-ant-xxxx",
"model": "claude-sonnet-4-6"
},
"channels": ["discord"],
"workspace": "/workspace/coder"
},
"researcher": {
"model": {
"provider": "openai",
"apiKey": "sk-xxxx",
"model": "gpt-4o"
},
"channels": ["slack"],
"workspace": "/workspace/researcher"
}
}
}

复制代码

多 Agent 操作命令：

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

复制代码

全局参数：

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

复制代码

第5章 Agent 人格定制

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

25位大厂高管转战生成式AI创业！吸金猛，不

OpenClaw 从入门到精通

浏览过的版块

LangGraph

关于我们

产品与服务

解决方案

产品与服务