第1章 认识 OpenClaw用一句话解释OpenClaw 是一个跑在你自己电脑或服务器上的私人 AI 助手。你可以把它想象成一个24小时在线的私人管家——它不住在云端不像 ChatGPT 网站而是住在你自己的机器里听你的话按你的方式工作。它不是一个聊天网站而是一个你可以自由控制、自由扩展、自由连接的 AI 平台。你可以让它在 Telegram/Discord/WhatsApp 上陪你聊天帮你管理邮件、日历自动执行代码、操作文件监控服务器、发告警通知甚至控制智能家居设备1.2 发展历程OpenClaw 不是一天诞生的它经历了三个重要阶段时间名称定位2024年Clawdbot龙虾机器人简单的聊天机器人2025年Moltbot升级为编码助手2026年OpenClaw完整的自主 AI Agent 平台为什么叫 Claw爪子名字来源于它的前身 ClawdbotClaw 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 12LinuxUbuntu 20.04 / Debian 11必备软件Node.js18 或更高版本运行 OpenClaw 的必备环境npmNode.js 的包管理器随 Node.js 一起安装网络要求稳定的互联网连接能访问你选择的 AI 模型 API如 Anthropic、OpenAI验证环境# 检查 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 模型你想用哪个模型Claude、GPT-4、Gemini 等输入 API Key你的模型 API 密钥是什么选择频道想连接哪个聊天平台Telegram、Discord 等设置工作空间Agent 可以访问哪些目录安装守护进程是否设为开机自启一键完成所有设置含后台服务安装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添加{ channels: { telegram: { enabled: true, botToken: 你的BOT_TOKEN } } }第三步测试连接# 检查频道状态 openclaw channels status --probe如果显示 Telegram 连接正常说明成功了连接 Discord备选Discord 连接需要创建一个 Discord Application访问 https://discord.com/developers/applications创建新应用 → Bot → 复制 Token在openclaw.json中配置{ channels: { discord: { enabled: true, botToken: 你的DISCORD_BOT_TOKEN } } }2.5 启动与验证启动 GatewayGateway 是 OpenClaw 的核心服务负责管理所有连接。# 方式一后台启动推荐 openclaw gateway start # 方式二前台启动调试用可以看到实时日志 openclaw gateway run验证安装# 检查 Gateway 状态 openclaw gateway status # 检查模型连接 openclaw models status --probe # 检查频道连接 openclaw channels status --probe # 整体健康检查 openclaw status # 查看实时日志 openclaw logs --follow成功的标志openclaw gateway status显示服务正在运行你在 Telegram/Discord 给机器人发消息能收到回复openclaw logs --follow显示请求被正常处理2.6 常见问题排错问题 1openclaw命令找不到原因npm 全局安装路径未加入 PATH解决# Windows PowerShell $env:PATH ;$(npm config get prefix) # 永久解决将 npm prefix 路径加入系统环境变量 PATH npm config get prefix # 把输出的路径加入系统 PATH 环境变量问题 2Gateway 启动后立即退出原因端口被占用或配置有误解决# 用 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 的中央大脑一切请求都经过它。它负责接收来自各个频道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 enabledAgent 就像没有手的人——知道怎么做但做不到工具可以被启用或禁用出于安全考虑3.4 Skills 技能一句话解释Skill 是 Agent 的课本教 Agent 何时、如何使用工具来完成复杂任务。关键特征Skills 是Markdown 文件通常叫SKILL.md里面写的是 SOP标准操作流程告诉 Agent 怎么做一个 Skill 可以组合多个 ToolOpenClaw 有 53 官方技能可通过 ClawHub 安装类比理解如果 Tools 是手那 Skills 就是菜谱手会切菜、会开火但需要菜谱告诉你先做什么、后做什么有了菜谱Skill普通人也能做出一道复杂的菜Skill 文件示例# 代码审查技能 ## 何时使用 当用户发送代码或要求审查代码时 ## 执行步骤 1. 使用 read 工具读取代码文件 2. 分析代码结构、命名、逻辑 3. 指出潜在问题和安全风险 4. 使用 edit 工具给出修改建议 5. 输出审查报告3.5 Hands 手一句话解释Hands 是 7 个内置的自主能力模块让 Agent 能独立工作。每个 Hand 负责一类特定能力比如文件操作 Hand网络通信 Hand代码执行 Hand浏览器自动化 Hand等等Hands 和 Tools 的关系Hands 是能力分类大模块Tools 是具体操作小动作一个 Hand 包含多个 Tool3.6 Plugins 插件一句话解释Plugin 是超能力扩展包可以给 OpenClaw 增加全新的频道、工具、内存后端等。插件能做什么添加新的频道类型比如微信、企业微信添加新的工具比如控制智能家居添加新的存储后端比如用 Redis 代替本地文件存记忆添加新的认证方式类比理解如果 OpenClaw 是一部手机Plugins 就是APP手机本身功能有限装上 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 } } }结构解读agents— Agent 定义可以有多个default— Agent 名称model— AI 模型配置channels— 启用的频道列表workspace— 工作空间路径channels— 频道详细配置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] } } } }支持的模型供应商providerprovider对应模型示例 model 值anthropicClaudeclaude-sonnet-4-6,claude-opus-4-7openaiGPTgpt-4o,gpt-4o-minigoogleGeminigemini-2.0-flashopenrouter多模型聚合任意 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 restart4.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 code4.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 服务器配置MCPModel 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 } } } } }关键理解所有 MCP 服务器配置集中在openclaw.json的mcp.servers下Gateway 上的所有 Agent都能使用这些 MCP 工具MCP 服务器以独立进程运行通过 stdio 与 Gateway 通信4.6 工作空间 Workspace一句话解释Workspace 是 Agent 可以访问的文件系统边界是安全的第一道防线。配置方式{ agents: { default: { workspace: /home/user/openclaw/workspace/default } } }工作空间规则Agent只能访问 workspace 内的文件超出 workspace 范围的文件操作会被拒绝每个 Agent 可以有独立的 workspace默认 workspaceOPENCLAW_WORKSPACE_ROOT/agents/agent-name/检查当前 workspaceopenclaw config get agents.default.workspace4.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 人格定制
