OpenClaw V3 新手起飞指南 🚀
✨ 写在前面: 这是一份专门为你精简提炼的“保姆级”新手指南。 我们剔除了早期不需要懂的底层配置和部署逻辑,为你找到了一条最平缓的入门曲线 (Sweet Spot):
从零基础 -> 拿到 API -> 成功安装 -> 接入飞书 -> 安全防泄漏 -> 学会用技能
准备好了吗?系好安全带,我们要发车了!
第一部分:揭开面纱(OpenClaw 到底是什么)
🎯 本章目标:学完这章,你能向朋友清楚解释OpenClaw是什么、能做什么、不能做什么
⏱️ 预计时间:3分钟
本章你将学会什么
- • 用一句话向朋友解释OpenClaw是什么
- • 三个真实场景,理解它能帮你做什么
- • 澄清常见误解,知道它不能做什么
- • 为什么2026年它突然火了
- • 根据你的需求,选择最适合的阅读路径
1.1 一句话解释:你的AI助理,住在你的电脑里
想象一下:你招了一个实习生,这个实习生特别聪明,能帮你查资料、写文档、整理数据,还能24小时在线。但你不需要给它交社保,也不用担心它跳槽。
OpenClaw就是这个实习生,只不过它住在你的电脑里。
更准确地说:
OpenClaw是一个AI智能体平台(Agent Platform),让你能在自己的电脑上运行AI助理,并把它接入到你日常使用的工具里——比如飞书、Telegram。
几个核心概念,先混个脸熟(后面章节会详细讲):
- • Agent(智能体):能自主执行任务的AI程序,就像一个带工具箱的实习生。你告诉它"帮我整理今天的会议纪要",它会自己决定用什么工具、分几步完成。
- • Gateway(网关):系统的总调度室,负责消息路由和协调。默认地址是
127.0.0.1:18789,就是你电脑上开的一个端口。 - • Channel(渠道):连接各种聊天平台的接口,比如飞书、Telegram。
- • Tool(工具):Agent能调用的具体功能,比如读写文件、执行命令、搜索网页。
- • Skill(技能):告诉Agent什么时候用什么工具的"说明书"。
别慌,这些词现在看着陌生,用几遍就熟了。
1.2 它能做什么:三个真实场景
光说概念太虚,来看三个真实的使用场景。
1.2.1 场景一:自动整理日报(拯救打工人)
小王每天下班前要发日报,总结今天做了什么。以前他要翻聊天记录、看邮件、回忆一天的工作,至少花20分钟。
现在他@飞书里的OpenClaw机器人:
"帮我整理今天的日报,从项目群提取关键进展,从邮件提取待跟进事项。"
机器人自动:
-
- 读取指定群聊的今日消息
-
- 提取关键信息
-
- 按格式生成日报
-
- 发到指定文档
省下的20分钟,小王可以准时下班了。
1.2.2 场景二:查资料写报告(研究员的福音)
小李需要写一篇行业分析报告,涉及大量资料搜集。以前他要在十几个网站间来回切换,复制粘贴到手软。
现在他告诉OpenClaw:
"搜索2025年AI编程助手的市场规模,整理成表格,包含数据来源。"
Agent自动:
-
- 调用搜索工具查找资料
-
- 访问多个网页提取信息
-
- 整理成结构化表格
-
- 标注数据来源
小李从"体力活"中解放出来,专注在分析和判断上。
1.2.3 场景三:飞书里@它办事(团队协作神器)
团队群里经常有人问:
- • "谁能查一下上个月的销售数据?"
- • "帮忙翻译一下这个英文文档"
- • "把这份PDF转成Markdown"
现在直接在群里@机器人:
"@小助手 把刚才发的PDF转成Markdown格式"
机器人立即处理,把结果发回群里。
不用麻烦同事,不用切换工具,在聊天中就把事办了。
1.3 它不是什么:澄清常见误解
OpenClaw很强大,但它不是万能的。以下几个误解,越早澄清越好。
1.3.1 误解一:它是ChatGPT替代品
不是。
ChatGPT是一个AI对话产品,你打开网页就能聊。OpenClaw是一个平台,让你能搭建自己的AI助理。
你可以这样理解:
- • ChatGPT = 一个训练有素的客服
- • OpenClaw = 一个可以训练自己客服的系统
实际上,OpenClaw可以接入ChatGPT的API,也可以接入Claude、KIMI、MiniMax等其他模型。它是模型的使用者,不是模型的竞争者。
1.3.2 误解二:它是云端服务,数据存在别人服务器上
不是。
这是OpenClaw最大的特点之一:它运行在你的电脑上。
- • 你的聊天记录存在本地
- • 你的文件处理在本地完成
- • 你的API Key不会经过第三方服务器
对于担心数据隐私的企业和个人,这是巨大的优势。
⚠️ 注意:虽然OpenClaw本身在本地运行,但它调用AI模型时需要联网。你的消息会发送到对应的AI服务商(如OpenAI、KIMI等)。
1.3.3 误解三:它会自己上网乱买东西、乱发邮件
不会。
OpenClaw的设计理念是最小权限原则。默认情况下,它什么都不能做。
- • 想让它读写文件?你需要明确授权
- • 想让它发邮件?你需要配置邮件工具
- • 想让它执行命令?你需要开启沙箱并设置权限
而且,高风险操作可以设置二次确认,确保它不会"自作主张"。
1.4 为什么2026年它突然火了
AI Agent的概念不是2026年才有的,为什么现在才火?
1.4.1 原因一:大模型能力到了"可用"的临界点
2024年的GPT-4和Claude 3已经很强,但还不够稳定。2025-2026年的模型(Claude Opus 4.6/Sonnet 4.6、GPT-5.3-Codex、KIMI K2.5等)在理解复杂指令和稳定输出格式上有了质的飞跃。
简单说:以前的AI助理经常"听不懂人话",现在的能听懂了。
1.4.2 原因二:工程化工具成熟了
光有聪明的大脑不够,还需要:
- • 稳定的消息收发机制
- • 可靠的工具调用框架
- • 安全的权限管理系统
- • 友好的配置界面
OpenClaw把这些工程难题都解决了,让普通用户也能搭起自己的AI助理。
1.4.3 原因三:从"玩具"到"工具"的转变
早期的AI Agent更多是极客的玩具,现在它们真的能解决实际工作问题。
- • 整理日报节省20分钟
- • 查资料写报告节省2小时
- • 自动化数据处理节省半天
当省下的时间超过学习成本时,普及就水到渠成了。
1.5 阅读路线图:三种读者的最短路径
这本书有17章,但你不需要全部读完。根据你的需求,选择最适合的路径:
1.5.1 路径A:我只想快速用起来(推荐所有人先走这条)
目标:在飞书里@AI机器人,让它帮你办事
阅读顺序:
-
- 第1章(本章)→ 了解是什么
-
- 第2章 → 准备API Key
-
- 第3章 → 安装OpenClaw
-
- 第5章 → 接入飞书
-
- 第6章 → 配置安全策略
预计时间:2-3小时
1.5.2 路径B:我想深度定制,让它做特定任务
目标:让AI助理完成我的专属任务(如数据分析、报告生成)
阅读顺序:
-
- 先完成路径A(基础必须打牢)
-
- 第10章 → 了解Tools能做什么
-
- 第11章 → 使用现成Skills
-
- 第12章 → 写第一个Skill
-
- 第13章 → 进阶优化
预计时间:1-2天
1.5.3 路径C:我是技术用户,想部署到服务器
目标:在服务器上稳定运行,团队共享使用
阅读顺序:
-
- 先完成路径A(了解基础)
-
- 第7章 → 模型配置优化
-
- 第8章 → 配置文件深入
-
- 第9章 → 安全与沙箱
-
- 第15章 → 多Workspace配置
-
- 第16章 → 部署与运维
预计时间:2-3天
本部分小结
来,我们回顾一下:
-
- OpenClaw是什么:一个AI智能体平台,让你的电脑上运行AI助理
-
- 它能做什么:整理日报、查资料写报告、飞书里@它办事
-
- 它不能做什么:不是ChatGPT替代品、不是纯云端服务、不会擅自行动
-
- 为什么现在火了:大模型能力成熟 + 工程化工具完善 + 真正解决工作问题
-
- 怎么开始:根据你的需求选择路径A、B或C
动手试试
-
- 向一位朋友解释OpenClaw是什么,用本章的"带工具箱的实习生"类比
-
- 思考:你日常工作中有哪些重复性任务,可能适合交给AI助理?
-
- 根据1.5节的路线图,确定你要走哪条路径
第二部分:开工准备(你只需要这三样东西)
🎯 本章目标:学完这章,你能确认自己具备开始的所有条件,并准备好API Key
⏱️ 预计时间:10分钟
本章你将学会什么
- • 确认你的电脑满足运行条件
- • 理解API Key是什么,以及怎么获取
- • 国内三家Coding Plan的详细申请步骤(KIMI/MiniMax/GLM)
- • 备选方案(OpenRouter/Anthropic)
- • 提前预览最终效果
2.1 别慌,你只需要这三样东西
很多技术书一上来就列一堆要求,看得人想放弃。咱们换个方式:
你只需要三样东西:
-
- 一台能上网的电脑(Windows/Mac/Linux都行)
-
- 一个API Key(别被这个词吓到,就是一串密码)
-
- 10分钟时间(和一点点耐心)
没了。不需要你是程序员,不需要你懂AI,不需要买服务器。
2.2 第一样东西:一台电脑
2.2.1 系统要求
| 系统 | 要求 | 备注 |
|---|---|---|
| macOS | 10.15+ | Intel和Apple Silicon都支持 |
| Windows | 10/11 | 推荐用WSL2(后面会讲) |
| Linux | 主流发行版 | Ubuntu/Debian/CentOS/Fedora都行 |
简单说:只要是近5年的电脑,基本都能跑。
2.2.2 网络要求
你需要能访问:
- • npm registry(安装OpenClaw)
- • 你选择的AI服务商(如KIMI、MiniMax等)
国内用户注意:OpenClaw本身不需要翻墙,但部分AI服务商可能需要。
2.3 第二样东西:一个API Key
2.3.1 API Key是什么?
API Key(应用编程接口密钥),听起来很高大上,其实就是一串密码。
类比一下:
- • 饭店的VIP卡 → 证明你有资格享受服务
- • 小区的门禁卡 → 证明你有权限进入
- • API Key → 证明你有权限调用AI服务
每次OpenClaw让AI帮你干活,都要出示这个Key。AI服务商根据Key来:
-
- 确认你是谁
-
- 计算你用了多少额度
-
- 决定是否响应你的请求
2.3.2 国内三家Coding Plan(推荐)
对于国内用户,我推荐优先选择以下三家。它们都有专门针对开发者的 Coding Plan,且本章统一使用国内站口径(不使用国际站路径)。
2.3.2.1 方案A:KIMI Coding Plan(推荐)
申请步骤:
-
- 访问 https://www.kimi.com/code
-
- 登录/注册KIMI账号
-
- 点击"订阅Coding Plan"
-
- 完成支付(支持支付宝/微信)
-
- 进入控制台,点击"创建API Key"
-
- 复制生成的Key(以
sk-开头)
- 复制生成的Key(以
💡 提示:Key创建后只显示一次,务必保存好。如果丢了,只能重新创建。
2.3.2.2 方案B:MiniMax Coding Plan(推荐)
申请步骤:
-
- 访问 https://platform.minimaxi.com/subscribe/coding-plan
-
- 注册/登录账号
-
- 完成实名认证(需要身份证)
-
- 订阅Coding Plan
-
- 进入"API管理"页面
-
- 创建API Key并复制
2.3.2.3 方案C:GLM Coding Plan(推荐)
申请步骤:
-
- 访问 https://bigmodel.cn/glm-coding
-
- 注册/登录智谱AI账号
-
- 进入控制台
-
- 点击"API Keys"菜单
-
- 创建新的API Key
-
- 复制保存
2.3.3 三家对比表
| 特性 | KIMI | MiniMax | GLM |
|---|---|---|---|
| 月费(2026-02-18核验) | 49/99/199/699元 | 29/49/119元 | 49/149/469元 |
💡 说明:以上价格均按御三家国内站结算页口径记录;后续如有活动变动,请以实时页面为准。
2.3.4 备选方案
如果上述三家都不适合你,还有以下选择:
2.3.4.1 OpenRouter
特点:一个API对接多家模型(Claude、GPT、Llama等) 网址:https://openrouter.ai 适合:想用一个Key调用多种模型的用户 注意:国内访问可能需要代理
2.3.4.2 Anthropic(Claude官方)
特点:Claude模型官方API,质量顶尖 网址:https://console.anthropic.com 适合:追求最高质量回复的用户 注意:国内访问需要代理,价格较高
2.4 第三样东西:10分钟时间
这10分钟你要做什么?
| 时间 | 动作 |
|---|---|
| 2分钟 | 检查电脑系统版本 |
| 5分钟 | 申请API Key(如果还没申请) |
| 3分钟 | 把Key保存在安全的地方 |
保存Key的建议:
-
- 不要直接保存在微信/QQ聊天记录里
-
- 不要截图保存在相册里
-
- 推荐保存在:
- • 密码管理器(1Password、Bitwarden等)
- • 本地文本文件(放在安全的位置)
- • 备忘录(如果支持加密)
⚠️ 重要:API Key就像银行卡密码,泄露了别人就能花你的钱。妥善保管!
2.5 提前看看你会得到什么
完成本书学习后,你将拥有:
一个能在飞书里@的AI机器人:
- • 私聊问它问题
- • 群里@它办事
- • 让它帮你整理文档、查资料
一个可定制的AI助理:
- • 根据你的需求写Skills
- • 连接你的常用工具
- • 自动化重复工作
完全掌控的数据隐私:
- • 所有数据存在本地
- • 不经过第三方服务器
- • 企业级安全保障
本部分小结
来,检查一下你的准备清单:
- • 一台能上网的电脑(Windows/Mac/Linux)
- • 一个API Key(KIMI/MiniMax/GLM任选其一)
- • 10分钟时间
如果都准备好了
动手试试
-
- 确认你的电脑系统版本符合要求
-
- 选择一家Coding Plan,完成API Key申请
-
- 把Key保存在安全的地方(推荐密码管理器)
-
- 测试网络:访问你选择的AI服务商控制台,确认能正常打开
第三部分:极速安装(5分钟把神兽接回家)
🎯 本章目标:学完这章,你能完成OpenClaw安装并发出第一条消息
⏱️ 预计时间:5分钟
📋 前置要求:已完成第2章(准备工作)
本章你将学会什么
- • 检查并安装Node.js环境
- • 用一行命令安装OpenClaw
- • 运行向导完成初始化配置
- • 理解QuickStart和Manual的区别
- • 配置国内三家Coding Plan
- • 验证安装成功并发出第一条消息
3.1 环境检查:Node.js是什么?
3.1.1 Node.js简介
Node.js是一个让JavaScript能在电脑本地运行的环境。简单说:
Node.js就像JavaScript的"翻译官",让它能在浏览器之外的地方工作。
你不需要深入理解它,只需要确认电脑上已经安装了。
3.1.2 检查Node.js版本
打开你的终端(Terminal),输入:
node --version
期望看到的结果:
v22.x.x
判断标准:
- • ✅ 版本 >= v22:可以继续
- • ❌ 版本 < v22:需要升级
- • ❌ 提示"command not found":需要安装
3.1.3 如果Node.js不符合要求
macOS安装/升级
## 使用Homebrew安装(推荐)brew install node# 如果已安装但版本低,升级brew upgrade node
Windows安装/升级
推荐方式:使用winget
winget install OpenJS.NodeJS.LTS
或者手动下载:
-
- 访问 https://nodejs.org
-
- 下载LTS版本(长期支持版)
-
- 按向导安装
💡 Windows用户注意:官方推荐在WSL2中运行OpenClaw,能避免很多奇怪问题。WSL2安装指南:https://docs.microsoft.com/zh-cn/windows/wsl/install
Linux安装/升级
Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -sudo apt-get install -y nodejs
CentOS/RHEL/Fedora:
sudo dnf install nodejs
3.1.4 验证安装
安装完成后,再次检查:
node --versionnpm --version
两个命令都应该返回版本号。
⚠️ 常见问题:如果安装后还是提示"command not found",尝试重启终端或重新登录系统。
3.2 安装命令:就一行,复制粘贴
确认Node.js >= v22后,执行安装命令:
npm install -g openclaw@latest
这行命令在做什么?
- •
npm:Node.js的包管理器 - •
install:安装 - •
-g:全局安装(在任何目录都能用openclaw命令) - •
openclaw@latest:安装 npm 上当前发布版(本书核验冻结点为v2026.2.17)
等待时间:取决于你的网络,通常30秒到2分钟。
3.2.1 验证安装成功
openclaw --version
期望看到类似输出:
2026.2.17
❌ 如果提示"command not found"
可能原因:npm全局路径未加入系统PATH
解决方法:
- 重启终端
- 如果还不行,检查npm全局路径:
npm prefix -g
- 把返回的路径加入PATH环境变量
3.3 运行向导:openclaw onboard
安装完成后,运行初始化向导:
openclaw onboard --install-daemon
参数说明:
- •
onboard:运行初始化向导 - •
--install-daemon:同时安装后台服务(推荐)
3.3.1 向导第一步:风险确认 + 已有配置处理
启动向导后,通常会先看到:
? I understand this is powerful and inherently risky. Continue?❯ Yes No
这里选 Yes 继续。
如果你之前装过 OpenClaw,还会看到:
Existing config detected...? Config handling❯ Use existing values Update values Reset
怎么选:
- • 首次安装:通常不会出现这一段,直接进入下一步。
- • 复装/换模型:选
Update values(推荐,保留其余稳定配置)。 - • 完全重来:选
Reset(谨慎)。
3.3.2 向导第二步:选择模式(Onboarding mode)
向导会问你:
? Onboarding mode❯ QuickStart - Minimal setup, get running fast Manual - Full control over all settings
怎么选?
| 选项 | 适合谁 | 结果 |
|---|---|---|
| QuickStart | 新手,想快速跑起来 | 自动配置推荐设置 |
| Manual | 想完全掌控配置 | 逐个配置每个选项 |
我的建议:第一次选 QuickStart,后面可以随时改配置。
3.3.3 向导第三步:先选模型厂商(Provider)
向导会提示你选择模型提供商:
? Which model provider would you like to use? OpenAI Anthropic❯ KIMI MiniMax GLM Other (custom endpoint)
先选你在第2章申请的厂商(KIMI / MiniMax / GLM)。
3.3.4 向导第四步:再选鉴权方式(Auth method,容易漏)
在你选完厂商后,通常不会立刻要 Key,而是先进入该厂商的鉴权方式选择。
常见会看到类似:
? <Provider> auth method❯ Coding Plan / OAuth API Key
国内读者建议:优先选 Coding Plan 对应项。
- • KIMI:优先
Kimi Code API key (subscription)路径 - • MiniMax:优先
MiniMax OAuth(CN)路径 - • GLM(Z.AI):优先
Coding-Plan-CN路径
3.3.5 向导第五步:输入API Key并选模型
如果选择KIMI
? Enter your KIMI API Key: [粘贴你的Key]? Select model: ❯ kimi-k2.5
如果选择MiniMax
? Enter your MiniMax API Key: [粘贴你的Key]? Select model: ❯ MiniMax-M2.5
如果选择GLM
? Enter your GLM API Key: [粘贴你的Key]? Select model: ❯ glm-5
💡 提示:粘贴API Key时,终端不会显示任何字符(为了安全),这是正常的。直接粘贴后按回车即可。
3.3.6 向导第六步:配置Channel(先Skip!)
在 QuickStart 路径下,向导会直接进入渠道单选列表:
? Select channel (QuickStart) ... Feishu/Lark (飞书) ...❯ Skip for now (You can add channels later via `openclaw channels add`)
首次建议直接选 Skip for now。
为什么先Skip?
这是多轮实测验证出的最佳实践:
-
- 先把"TUI里能稳定对话"跑通
-
- 确认模型、鉴权、Gateway都正常
-
- 再接入渠道,出错时能明确判断是"渠道配置问题"还是"基础环境问题"
放心,第5章会详细讲飞书接入。
3.3.7 向导第七步:配置 Skills(建议开)
Channel 之后,向导会进入 Skills 检查与可选安装:
Skills statusEligible: ...Missing requirements: ......? Configure skills now? (recommended)❯ Yes No
首次建议选 Yes,原因很简单:
现在就把“能自动装的依赖”装掉,后面少踩坑。
接下来常见会看到:
? Install missing skill dependencies❯ Skip for now <某个 skill 依赖项...>? Preferred node manager for skill installs❯ npm pnpm bun
给新手的默认建议:
-
- 如果你只想先跑通主线:可先
Skip for now;
- 如果你只想先跑通主线:可先
-
- 如果你准备立刻玩 Skills:按需勾选安装项;
-
node manager选你本机已经在用的那个(不确定就用npm)。
3.3.8 向导第八步:配置 Hooks(建议最小开启)
Skills 后会进入 Hooks 配置:
Hooks...? Enable hooks?❯ Skip for now <hook 列表...>
官方说明里,Hooks 用来“在某些命令触发时自动执行动作”(例如 /new 时做会话记忆整理)。
本书建议的最小策略:
-
- 首次可先启用 1 个最核心 hook(最小可用,优先
session-memory,若列表里有);
- 首次可先启用 1 个最核心 hook(最小可用,优先
-
- 如果你现在还分不清 hook 的作用,也可以先
Skip for now;
- 如果你现在还分不清 hook 的作用,也可以先
-
- 先跑通主线,后面在第10章再系统化管理 hooks。
3.3.9 向导第九步:选择 Hatch 方式(关键)
在收尾阶段,向导会给你一个启动入口选择:
? How do you want to hatch your bot?❯ Hatch in TUI (recommended) Open the Web UI Do this later
怎么选:
- •
Hatch in TUI (recommended):在终端里直接进入交互(最稳,推荐默认选这个) - •
Open the Web UI:打开浏览器控制台(图形化) - •
Do this later:先结束向导,稍后再进
为什么默认选 TUI:
-
- 我们无法假设你一定在本机操作;很多读者是在云主机/VPS 上跑。
-
- 如果是 VPS,
Open the Web UI往往还要做端口转发,对新手不友好。
- 如果是 VPS,
-
- 选
Hatch in TUI可以立刻开始对话,不被网络与端口问题卡住。
- 选
3.3.10 向导第十步:记录 Dashboard 链接与 Gateway 状态
在你完成 Hatch 选择后,向导会输出控制台访问信息与网关状态(如 Web UI、Gateway WS、Gateway: reachable)。
如果你选了 Open the Web UI,一般会直接给出带 token 的 Dashboard 链接并尝试自动打开浏览器。
如果你选了 Do this later,后续可用:
openclaw dashboard --no-open
再次获取控制台入口。
3.4 首次对话:先完成 bootstrap(真正初始化)
onboard 完成后,建议先在 TUI 里完成第一轮 bootstrap 对话。
官方流程会把它当成“把 Agent 变成你的 Agent”的关键动作(源码里有 Wake up, my friend! 引导)。
这一步建议你主动讲清楚下面 5 件事:
-
- 你是谁:怎么称呼你、你的时区和工作语言。
-
- 你要它扮演什么角色:比如“我的技术写作助手”。
-
- 你平时的工作场景:常用工具、文件目录、沟通方式(飞书/邮件等)。
-
- 你的偏好:回答风格、长度、是否先给结论。
-
- 你的边界:哪些操作必须先确认、哪些内容不要碰。
这一步做得越清楚,后续它越像“你自己的实例”,而不是“一个通用聊天机器人”。
💡 你也可以把这些信息落盘到工作区里的
BOOTSTRAP.md / IDENTITY.md / USER.md / SOUL.md,让后续会话更稳定。
3.5 Bootstrap 后,再发第一条“低上下文”消息
完成 bootstrap 后,建议先发一条不依赖你工作背景的消息做冒烟测试。
推荐你先用这条:
请给我一个“今天就能执行”的 5 条待办清单(每条不超过 18 个字),并按优先级排序。
如…