2 万字保姆级教程：OpenClaw V3 AI 智能体平台新手入门与实战指南

本文档旨在帮助零基础用户快速上手 OpenClaw AI 智能体平台，实现从零到一的部署与应用。教程结构清晰，采用“保姆级”引导，剔除了早期复杂的底层逻辑，专注于最平缓的入门路径。

✨ 第一部分：揭开面纱（OpenClaw 到底是什么）

​🎯 本章目标​：用 3 分钟时间，理解 OpenClaw 是什么、能做什么、不能做什么，以及为什么在 2026 年变得热门。

1.1 一句话解释：你的 AI 助理，住在你的电脑里

OpenClaw 是一个 ​AI 智能体平台（Agent Platform）​，它让你能在自己的电脑上本地运行一个 AI 助理，并将其接入到日常使用的工具（如飞书、Telegram）中。你可以将其理解为一个“自带工具箱的实习生”，能帮你查资料、写文档、整理数据，并 24 小时在线。

​核心概念速览​：

• ​Agent（智能体）​：能自主执行任务的 AI 程序。
• ​Gateway（网关）​：系统的总调度室，默认地址是 127.0.0.1:18789。
• ​Channel（渠道）​：连接各种聊天平台的接口，如飞书。
• ​Tool（工具）​：Agent 能调用的具体功能，如读写文件、搜索网页。
• ​Skill（技能）​：告诉 Agent“何时用何工具”的说明书。

1.2 它能做什么：三个真实场景

1. ​场景一：自动整理日报​：在飞书中 @ 机器人，可自动读取群聊消息、提取关键信息、按格式生成日报，省时高效。
2. ​场景二：查资料写报告​：通过指令让 Agent 自动调用搜索工具，访问多个网页提取信息，并整理成带来源的结构化表格。
3. ​场景三：飞书内 @ 办事​：在团队群聊中直接 @ 机器人，可处理如翻译文档、转换文件格式等请求，无需切换工具或麻烦同事。

1.3 它不是什么：澄清常见误解

• ​误解一​：它不是 ChatGPT 的替代品。OpenClaw 是一个​平台​，可以接入 ChatGPT、Claude、KIMI 等多种 AI 模型，是模型的使用者而非竞争者。
• ​误解二​：它不是纯云端服务。其最大特点之一是​运行在你的本地电脑上​，聊天记录和文件处理均在本地，API Key 不经过第三方服务器，数据隐私有保障。（注：调用 AI 模型时需联网，消息会发送至对应的 AI 服务商）。
• ​误解三​：它不会擅自行动。其设计遵循​最小权限原则​，默认无任何权限。所有高风险操作（如读写文件、执行命令）均需明确授权，并可设置二次确认。

1.4 为什么 2026 年它突然火了

1. ​大模型能力成熟​：2025-2026 年的模型在理解复杂指令和稳定输出格式上达到“可用”临界点。
2. ​工程化工具完善​：解决了消息收发、工具调用、权限管理等工程难题，让普通用户也能搭建。
3. ​从玩具到工具的转变​：能切实解决工作问题（如节省日报、报告时间），普及水到渠成。

1.5 阅读路线图：根据你的目标选择

• ​路径 A：快速用起来​（推荐所有人首选）：目标是在飞书里 @ 机器人办事。按顺序阅读第 1、2、3、5、6 章，预计 2-3 小时。
• ​路径 B：深度定制​：目标是让 AI 完成特定任务（如数据分析）。在完成路径 A 后，阅读第 10、11、12、13 章，预计 1-2 天。
• ​路径 C：技术部署​：目标是在服务器上稳定运行供团队使用。在完成路径 A 后，阅读第 7、8、9、15、16 章，预计 2-3 天。

🚀 第二部分：开工准备（你只需要这三样东西）

​🎯 本章目标​：用 10 分钟确认并准备好所有开始条件，重点是获取 API Key。

2.1 你只需要三样东西

1. 一台能上网的电脑（Windows 10/11, macOS 10.15+, 或主流 Linux）。
2. 一个 API Key（访问 AI 服务的“密码”）。
3. 10 分钟时间和一点耐心。

2.2 核心：获取 API Key（国内三家 Coding Plan 推荐）

API Key 是调用 AI 服务的凭证。对于国内用户，教程推荐优先选择以下三家的“Coding Plan”开发者套餐：

​💡 重要提示​：

• API Key​创建后只显示一次​，务必立即妥善保存（推荐使用密码管理器）。
• API Key 如同银行卡密码，泄露可能导致他人盗用你的额度。

⚡ 第三部分：极速安装（5 分钟把神兽接回家）

​🎯 本章目标​：完成 OpenClaw 的安装、初始化，并发出第一条消息。

​📋 前置要求​：已完成第二部分，准备好电脑和 API Key。

3.1 环境检查：安装 Node.js

OpenClaw 基于 Node.js 运行。打开终端，输入 node --version 检查。​版本需 >= v22​。若不符合，需安装或升级。

​安装命令示例​：

• ​macOS​: brew install node

• ​Windows​: winget install OpenJS.NodeJS.LTS 或从 nodejs.org 下载安装。

• ​Linux (Ubuntu)​:

  curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
  sudo apt-get install -y nodejs

3.2 安装 OpenClaw

在终端执行一行命令进行全局安装：

npm install -g openclaw@latest

安装完成后，运行 openclaw --version 验证。

3.3 运行初始化向导

执行以下命令启动交互式配置向导：

openclaw onboard --install-daemon

​关键配置步骤指引​：

1. ​模式选择​：新手选择 QuickStart 以快速完成。
2. ​选择模型厂商​：选择你已申请 API Key 的厂商（KIMI / MiniMax / GLM）。
3. ​鉴权与 Key​：根据提示选择对应的鉴权方式（如 Coding Plan），并粘贴你的 API Key。
4. ​选择模型​：通常选择该厂商的主力模型（如 KIMI 的 kimi-k2.5）。
5. ​配置 Channel​：​首次建议先选择 Skip for now​，优先保证基础功能通畅，飞书接入将在第五部分单独进行。
6. ​Skills 与 Hooks​：可先按推荐最小化配置或跳过。
7. ​启动方式​：推荐选择 Hatch in TUI (recommended)，直接在终端内启动并交互。

3.4 完成首次对话

1. ​Bootstrap（初始化）​：在 TUI 中，主动向 Agent 介绍你的身份、时区、工作语言、期望它扮演的角色、你的工作场景、回答偏好以及操作边界。这能将其定制为“你的”AI 助理。
2. ​发送测试消息​：完成 Bootstrap 后，发送一条不依赖上下文的业务消息进行测试，例如：“请给我一个‘今天就能执行’的 5 条待办清单（每条不超过 18 个字），并按优先级排序。” 收到结构化回复即表示安装成功。

📲 第四部分：飞书接入（让它能在群里陪你聊天）

​🎯 本章目标​：完成 OpenClaw 与飞书机器人的对接，实现在飞书私聊和群聊中使用 AI 助理。

​📋 前置要求​：已完成第三部分安装，且能在 TUI 中正常对话。

4.1 整体流程

1. ​飞书侧​：创建应用 -> 获取凭证(App ID/Secret) -> 配置权限 -> ​发布应用​。
2. ​OpenClaw 侧​：配置飞书渠道(openclaw channels add)。
3. ​连接​：启动 Gateway -> 在飞书开启“事件订阅”（长连接）。
4. ​安全​：在飞书与机器人私聊触发配对 -> 在 OpenClaw 中批准配对。
5. ​测试​：私聊与群聊测试。

4.2 详细步骤

Step 1: 在飞书开放平台创建并发布应用

1. 访问 https://open.feishu.cn/app，登录后点击“创建企业自建应用”。
2. 填写应用信息（名称、描述等）。
3. 在“凭证与基础信息”中，记录 App ID​ 和 ​App Secret​。
4. 在“权限管理”中，点击“批量导入权限”，粘贴教程提供的完整权限 JSON 配置。
5. 在“应用能力”中，找到并“启用”“机器人”能力。
6. ​【关键步骤】​：在“版本管理与发布”中，创建版本并“申请发布”。​必须等待应用审批通过变为“已发布”状态​，才能进行后续的长连接配置。

Step 2: 在 OpenClaw 中配置飞书渠道

1. 确保飞书插件启用：openclaw plugins enable feishu。
2. 运行交互式配置命令：openclaw channels add。
3. 按提示选择渠道类型为 Feishu/Lark (飞书)，输入 Step 1 中获取的 App ID 和 App Secret，域名选择 feishu.cn。
4. 群聊策略先选 disabled，等私聊通后再开。Require mention 务必选 yes（群里需 @ 才回复）。

Step 3: 开启事件订阅（长连接）

1. 在 OpenClaw 终端启动 Gateway：openclaw gateway start。
2. 回到飞书开放平台，进入“事件与回调”。
3. 在“事件订阅方式”中选择“长连接”，并保存。
4. 在“订阅事件”区域，添加 im.message.receive_v1 事件。

Step 4: 配对与测试

1. 在飞书 App 中搜索你的机器人名称，进入私聊界面发送任意消息（如“你好”）。
2. 机器人会回复一条包含​配对码（Pairing code）​的消息。
3. 在 OpenClaw 终端执行批准命令：openclaw pairing approve feishu <配对码>。
4. 批准后，再次在飞书私聊中发送消息，机器人应能正常回复。

Step 5: 开启群聊（可选）

私聊测试无误后，可修改渠道配置开启群聊功能，并将机器人拉入飞书群组。在群内 @机器人 提问，它将只回复被 @ 的消息。

🔐 第五部分：安全防护（别让它在公司大群乱回消息）

​🎯 本章目标​：配置飞书渠道的安全策略，防止机器人被滥用或误操作。

5.1 私聊策略

• ​pairing（推荐）​：用户首次私聊需管理员批准。最安全，适合企业内部。
• ​allowlist​：仅允许白名单内的用户私聊。
• ​all（不推荐）​：任何人都可私聊，存在滥用风险。

5.2 群聊策略

• ​requireMention（必须开启）​：机器人在群里​只回复 @ 它的消息​，无视其他讨论。这是防止机器人在大群中“乱入”回复的关键保险栓。
• ​群聊白名单​：可配置 groupAllowFrom，限制机器人只被允许加入特定的群组。

5.3 上线前风控 Checklist

1. ✅ 私聊策略非 all（建议 pairing）。
2. ✅ 群聊已开启 requireMention。
3. ✅ 已配置必要的群聊/用户白名单。
4. ✅ 已设置 API 调用月度预算上限（openclaw config set budget.monthly 50）。
5. ✅ 已审查并限制 Agent 可用的高风险 Tools（如 execute_command）。

5.4 常见问题排查

• ​长连接订阅失败​：检查应用是否已“发布”；检查 Gateway 是否已启动。
• ​消息无回复​：检查用户配对状态(openclaw pairing list)；检查 Channel 状态和日志(openclaw logs)。
• ​@ 机器人没反应​：确认 requireMention 已开启；确认 @ 了正确的机器人；查看日志确认是否收到消息。

🧠 第六部分：挑选大脑（KIMI、MiniMax、GLM 怎么选）

​🎯 本章目标​：根据需求选择合适的 AI 模型，并完成配置与成本监控。

6.1 模型选择建议

• ​长文档处理、深挖分析​：优先试用 KIMI​ (moonshot/kimi-k2.5)，其长上下文能力突出。
• ​响应速度优先、快速对话​：优先试用 MiniMax​ (minimax/MiniMax-M2.5)，往返轻快。
• ​通用任务、均衡体验​：优先试用 GLM​ (zai/glm-5)。

​💡 建议​：先用你已开通套餐的一家跑通流程，再按任务类型切换测试。

6.2 模型切换与灾备

可以在配置中设置主模型（primary）和备用模型（fallbacks）列表。当主模型调用失败时，系统会自动按顺序切换至备用模型，保证服务可用性。

6.3 成本监控

• ​设置预算​：openclaw config set budget.monthly 50 设置月度预算上限。
• ​查看用量​：openclaw gateway usage-cost 查看各模型的使用量及费用统计。
• ​控制技巧​：简单任务用轻量模型；限制单次调用的最大 token 数；设置调用频率限制。

🛠️ 第七部分：装备技能（让它学会自动生成日报）

​🎯 本章目标​：学会从 ClawHub（OpenClaw 的 Skill 应用商店）搜索、安装和使用现成的 Skills，扩展 AI 助理的能力。

7.1 使用现成 Skills

• ​ClawHub​：Skills 的公共注册中心，地址为 https://clawhub.com。
• ​搜索 Skills​：在终端中使用 openclaw skills list --eligible “关键词” 进行搜索。
• ​“安装”与调用​：Skills 通常无需手动安装，当 Agent 识别到任务需要某个 Skill 时，会自动检索并拉取。用户直接在对话中提出需求即可（如“运行 daily-report 生成今天的日报”）。
• ​检查状态​：使用 openclaw skills list --eligible 检查已就绪可用的 Skills。

7.2 推荐 Skills 清单

• ​生产力类​：daily-report（自动日报）, meeting-notes（会议纪要）, email-digest（邮件摘要）。
• ​开发类​：github-pr-helper（PR 审查）, code-review（代码审查）。
• ​内容类​：article-summarizer（文章摘要）, translation-helper（翻译助手）。

🎉 结语

至此，你已成功完成了 OpenClaw 的入门之旅。你拥有了一部署于本地、接入飞书、安全可控、且具备扩展能力的专属 AI 助理。接下来，你可以探索更深入的定制，或直接用它来解放生产力，自动化日常工作中的重复性任务。