2026/9/9 18:09:34
FEATURED · 精选文章 
你们催的 OpenClaw 安装教程来了其实我早就想写了但一直觉得这玩意儿对小白不太友好直接扔一堆命令出去容易把人劝退。这次我把完整流程重新走了一遍从零开始、不看文档、不写代码把每一步卡住的地方都记录下来整理成了一套适合新手的操作路径。标题说 6 分钟安装是真的但前提是你把模型服务的 API Key 提前准备好不然卡在初始化环节别怪我。OpenClaw 这个名字圈子里玩过的应该都熟它其实就是之前的 Clawdbot一个开源的 AI 智能体框架。简单说它能让你用自然语言指挥 AI 去执行实际任务而不只是陪你聊天。写小说、读文档、调接口、定时跑脚本、挂在飞书群里当机器人这些都能干。这篇教程覆盖 Windows、macOS、Linux 三种环境装完以后跑不起来的直接翻到最后一节的报错排查手册对照着查。1. OpenClaw和Clawdbot到底是个什么东西别把它当成普通聊天机器人1.1 从Clawdbot改名到OpenClaw它解决了什么问题先说背景。Clawdbot 是早期项目名后来正式更名为 OpenClaw所以你在网上搜的时候两个名字对应的是同一个东西。我理解它是在做一个“AI 代理运行环境”你给模型一个目标它自己判断需要调用哪些工具然后一步步把任务做完。这个思路和普通聊天窗口完全不一样。传统聊天机器人是你一句它一句输出完就结束了上下文断了也不管。OpenClaw 的设计是它会带着任务去调度工具比如读写文件、执行命令、请求外部 API、搜索本地资料甚至通过消息平台和人对谈整个流程可以被编排成一套可复用的“技能”。早期版本里这个编排层叫 Harness社区里也有人拿它和 Hermes 之类的项目做对比本质上都是在解决“模型怎么在真实环境里稳定干活”的问题。1.2 它到底能干什么几个最常见的使用场景我实际用下来比较典型的使用场景有这几个挂到聊天群里做自动问答和群管把 OpenClaw 接进飞书、钉钉、微信生态的机器人群里有人提问它会调用文档或搜索工具来回答还能帮你收集回复内容。自动写小说并落盘通过自定义 skill让模型按照设定生成章节保存到本地目录不需要手动复制粘贴。读文档、整理摘要丢给它一份 PDF 或 Markdown它自己抽取内容、生成结构化摘要。定时任务和数据处理通过技能脚本定时抓取数据、处理表格、发通知相当于给自己配了个自动化助理。个人知识库问答配合 Active Memory 长期记忆让机器人记住你之前交代过的背景资料下次对话不用重复解释。1.3 它和“聊天机器人”最大的区别在哪里关键在于“执行闭环”。普通聊天模型只负责生成文本OpenClaw 在生成文本之外还负责执行动作、观察结果、修正方向。你可以把它理解成“模型有了手和脚”模型就像是大脑技能脚本是手文件系统和 API 是它可以操作的对象。对小白来说你不需要一开始就理解这整套机制。只需要知道安装完以后你可以在聊天界面用自然语言让它“帮我读一下当前目录下的 data.xlsx统计一下总金额”它会自己去调 Python 脚本、读文件、返回结果。这就是它的价值。2. 动手前两分钟系统、依赖和模型服务先确认到位2.1 硬件和操作系统要求先说结论Windows 10/11、macOS 12 以上、主流 Linux 发行版Ubuntu、Debian、CentOS 都试过都能跑。虚拟机也能装但如果你用 VM 跑建议给虚拟机至少 2 核 4G 内存否则启动会很慢云服务器我用的腾讯云轻量应用服务器2 核 2G 跑基础版没问题但如果你打算加载本地模型做离线推理内存至少 8G 起步否则模型加载那一刻基本卡死。Mac mini 用户我单独说一句Apple Silicon 芯片跑 Docker 部署很顺M 系列芯片对很多模型的推理有加速用 Docker 装 OpenClaw 是最省心的一条路。Windows 用户注意PowerShell 执行策略默认限制脚本运行第一次跑安装脚本时大概率会被拦后面我会写怎么处理。2.2 依赖环境Node.js、Git还有 Docker 选装OpenClaw 的运行环境主要依赖 Node.js目前要求 18 以上推荐 20 LTS 版本。Git 也要装因为很多技能包和扩展从仓库拉取没有 Git 会卡在依赖下载那一步。Docker 属于选装但如果你懒得折腾本地 Node 环境走容器化部署会省很多事。装完 Node 以后有个常见坑终端关闭再重开后node 命令找不到。这是 PATH 环境变量没有刷新的问题Windows 下特别常见。我一般建议装完以后完全退出终端重新开一个新的窗口再试node -v确认能输出版本号再往后走。2.3 模型服务选型远程 API 还是本地模型这一步非常关键因为安装过程需要你选一个模型服务。两种方案各有优劣我列个表格你直接照着选方案优点缺点推荐配置远程 APIDeepSeek、通义千问等速度快不需要好显卡按量付费需要联网注册账号拿 API Key填进配置本地模型Ollama Qwen/Llama 等免费、隐私好、可离线吃配置部署麻烦一些16G 内存起步推荐 32G如果你只是为了体验流程我用 DeepSeek 的远程 API 确实最省心。如果你有本地 RTX 显卡或者 Mac 的统一内存比较大那直接上 Ollama 跑 Qwen 系列也够用。有一点先提醒本地模型跑 OpenClaw 时模型加载完之后的响应速度取决于你的显存/内存带宽不要期望太高先用小尺寸模型做验证。3. 六分钟实操跑通从第一条命令到Control UI弹出3.1 第 1 分钟先检查环境别等报错才回头打开终端依次执行下面三条命令node -v git --version docker --version第一条必须能输出版本号比如 v20.11.1第二条确认 Git 已安装第三条如果没装 Docker 不影响后面流程只是 Docker 部署路径用不了。如果 node 命令找不到回到第 2.2 节处理 PATH 问题。这一步的耗时排在第一分钟是因为很多人跳过它直接装结果装到一半才报环境错误反而更浪费时间。3.2 第 2~3 分钟执行官方安装脚本OpenClaw 提供一键安装脚本Linux 和 macOS 在终端执行curl -fsSL https://openclaw.ai/install.sh | bashWindows 用户在 PowerShell 里执行irm https://openclaw.ai/install.ps1 | iex这里我必须强调一句不要无脑复制网上的命令。执行之前先去官方仓库或官网核对一下脚本地址是不是最新版本因为这类安装脚本经常更新。另外curl | bash这种操作会把远程脚本直接交给 shell 执行有一定风险稳妥的做法是先把脚本下载下来看一遍再跑尤其是涉及文件写入的操作。安装过程会拉取依赖耗时跟你网络情况有关一般一两分钟。看到类似 “OpenClaw installed successfully” 的输出就算成功了。Windows 如果提示 “无法加载文件...因为在此系统上禁止运行脚本”在 PowerShell 里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重新跑安装命令。3.3 第 4 分钟初始化配置填模型和 API Key安装完成后执行openclaw init这个命令会引导你选择模型服务商、填写 API Key、确认一些基础配置。它会自动生成配置文件路径在~/.openclaw/config.json或~/.openclaw/config.yaml取决于版本。如果你用的是 DeepSeek直接在提示符里选 deepseek然后把 API Key 粘贴进去就行。如果你用的是 Ollama 本地模型这里要注意init 向导里可能不会直接列出本地模型你需要手动编辑配置文件把模型名改成你通过ollama list能看到的名称比如qwen2.5:7b。这一步是很多人卡住的地方后面第 4 节我专门写配置细节。3.4 第 5~6 分钟启动服务、打开 Control UI、发第一条消息初始化完成以后执行openclaw start正常启动后终端会输出 Control UI 的地址通常是http://localhost:3000或者http://localhost:8080。在浏览器打开这个地址你会看到一个聊天界面。在聊天框输入一句简单的测试指令比如你好请介绍一下你自己并告诉我你当前使用的模型名。如果它能正常回复说明整条链路已经通了。整个流程顺利的话前后确实只要五六分钟前提是 API Key 有效、依赖环境没出问题。3.5 备用安装路径Docker 和云服务器说明不想污染本机环境的话Docker 部署更干净。确保 Docker 已经启动然后执行docker run -d --name openclaw -p 3000:3000 -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest注意先把宿主机~/.openclaw目录建好否则挂载目录权限容易出问题。mac mini 用户用这个方式最省事。云服务器部署时记得在服务器的安全组里面放行 Control UI 对应的端口否则本地浏览器访问不到。不过这里也提醒一句如果服务器没有加 HTTPS 或者访问控制直接暴露端口会有被扫的风险我一般建议只在本地跑或者用 SSH 隧道访问别直接裸奔到公网。4. 模型接入是最大的坑DeepSeek、通义和Ollama的配置模板4.1 配置文件到底长什么样安装完以后配置文件~/.openclaw/config.yaml里模型相关的核心字段大概是这样的model: provider: deepseek name: deepseek-chat apiKey: sk-xxxxxxxxxxxxxxxx baseURL: https://api.deepseek.com/v1不同版本的字段名可能有差异但核心逻辑都一样provider 指定服务商name 指定模型名称apiKey 是密钥baseURL 是 API 地址。OpenAI 格式的兼容接口几乎都是这套参数。很多报错都集中在 name 这个字段上。模型名必须和服务商提供的名称精确一致多一个字母、少一个横杠都不行。我见过太多人把deepseek-chat写成deepseek_chat或者把qwen2.5:7b写成qwen2.5-7b结果启动的时候报一堆奇怪错误。4.2 三个常见模型服务商的配置模板直接照着抄DeepSeekmodel: provider: deepseek name: deepseek-chat apiKey: sk-你的key baseURL: https://api.deepseek.com/v1通义千问DashScope 兼容模式model: provider: openai name: qwen-max apiKey: sk-你的key baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1Ollama 本地模型model: provider: openai name: qwen2.5:7b apiKey: ollama baseURL: http://localhost:11434/v1Ollama 的 apiKey 随便填一个非空字符串就行因为它本地不校验。4.3 多模型切换不用来回改配置OpenClaw 支持配置多个模型在配置里以列表形式写出来然后通过环境变量或者在 init 里选择默认模型。大致结构是models: - name: deepseek-chat provider: deepseek apiKey: sk-xxx baseURL: https://api.deepseek.com/v1 - name: qwen2.5:7b provider: openai apiKey: ollama baseURL: http://localhost:11434/v1这样想切换的时候不用改文件在 Control UI 或启动参数里指定模型名就行。我自己习惯是一个付费模型做日常问答一个本地模型做隐私数据处理两条链路互不干扰。4.4 “unknown model”报错的真正原因和排查方法这是安装后出现频率最高的报错之一报错长这样agent failed before reply: unknown model: deepsee,oec-turbo看到这个报错先别慌原因基本只有一个配置里写的模型名模型服务商根本不认识。比如有人复制了某个演示文档里的模型名但那个模型命名可能是另一个平台的或者填 key 的时候格式错了导致配置没解析成功。排查方法按顺序做打开配置文件检查name是否和服务商文档一致。直接在浏览器访问服务的 API 文档页面确认模型名列表别凭记忆猜。本地测试接口连通性用 curl 直接发一个最小请求比如curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer sk-你的key看返回的 models 列表里有没有你填的名字。如果本地能通、OpenClaw 里不通十有八九是配置文件的缩进或格式问题打开配置检查引号、冒号、空格YAML 对这种缩进是非常敏感的。别小看这一步我观察过周围很多新手最后都卡在这里。5. 把OpenClaw接进飞书、钉钉和微信在聊天窗口里遥控AI5.1 平台接入的整体思路OpenClaw 本身不绑定任何聊天软件它通过连接器有些版本叫 channel 或 connector桥接到不同的 IM 平台。你在配置文件里加一段 channel 配置填入对应平台的机器人凭证它就能通过 Webhook 或长连接接收消息、回复消息。手机上的玩法也来自这里你不需要打开电脑上的 Control UI直接在聊天软件里发消息就能和它交互相当于把手机变成遥控器。5.2 飞书机器人配置最简单的一条路飞书接入的体验我觉得是三个里面最顺的。在开发者后台创建一个企业自建应用拿到 App ID 和 App Secret然后开启“机器人”能力在事件订阅里把 OpenClaw 的回调地址填进去。配置里大致加这一段channels: feishu: appId: cli_xxxxx appSecret: xxxxxx填完以后重启 OpenClaw去飞书里给你的机器人发一条消息试试。需要注意飞书的事件订阅要求回调地址必须是公网可访问的 HTTPS 地址内网环境下需要做内网穿透这一点要先想好。5.3 钉钉机器人配置要点钉钉的接入逻辑类似但钉钉更常用的是自定义机器人 Outgoing 机制。在钉钉群里添加自定义机器人设置 POST 回调地址并把加签密钥填到 OpenClaw 配置里。这样群里 机器人时OpenClaw 就能收到消息。钉钉有一点比较麻烦自定义机器人对消息格式要求比较严格单条消息有长度限制返回长文本时容易被截断。我实际使用中遇到回复比较长的情况会让 OpenClaw 先把内容写入文件或在线文档然后把链接返回给群聊体验会好很多。5.4 微信生态官方通道和个人号方案的风险差异微信是大家问得最多的但也是我建议要谨慎的地方。如果你是开发者优先考虑公众号或企业微信的官方机器人接口用微信官方提供的 API稳定且合规。个人微信号接入属于非官方方案市面上确实有一些协议库能实现但这类方案一直存在账号风控风险轻则功能被限制重则封号。我的个人建议是拿小号测试可以千万别把常用的工作微信号接进去也别用它跑重要业务。OpenClaw 社区里讨论的微信接入多数也是小号试玩。参与这类折腾前先看看官方机器人通道能不能满足需求能用官方就用官方。6. Skill技能接口从写小说到自定义API都能自己扩展6.1 Skill 到底是什么一个技能就是一个文件夹很多新手听到“Skill”会觉得很难其实它的本质就是一个约定格式的文件夹。OpenClaw 通过读取这个文件夹里的描述文件知道什么情况下该调用它然后执行里面的脚本。一个最小技能包的结构长这样my_skill/ SKILL.md run.shSKILL.md是给模型看的说明书描述这个技能是干什么的、参数是什么run.sh是给机器执行的动作脚本可以是 Shell、Python、JavaScript什么顺手用什么。6.2 SKILL.md 的写法关键是让模型看懂看一个最简单的示例--- name: get_time description: 获取当前时间和日期当用户询问“现在几点”或“今天几号”时使用。 parameters: - name: format description: 时间格式可选 short 或 full required: false --- 运行以下命令获取时间 bash run.sh {format}文件头部的 YAML 部分是对这个技能的元数据描述其中description最重要因为模型要根据它判断什么时候选这个技能。描述写得越具体模型选错的概率越低。6.3 实际案例给 OpenClaw 写一个“写小说”技能热词里有“openclaw 写小说”我就拿这个举例。假设你想让 OpenClaw 按提示词写小说章节并自动保存成文件技能包可以这样组织novel_writer/ SKILL.md write_novel.pywrite_novel.py接收两个参数小说标题和章节号调用模型接口生成内容然后保存到本地 novels 目录。SKILL.md 的描述部分这样写--- name: novel_writer description: 根据用户提供的小说主题生成章节内容并保存到本地文件当用户说“写小说”“生成章节”“继续写最新章节”时使用。 parameters: - name: topic description: 小说主题 required: true - name: chapter description: 章节号 required: false ---这样你在对话里说“用科幻主题写小说第三章”OpenClaw 就会调用这个技能。整个过程不需要你手动去 Model 接口调接口、写文件模型会自动完成参数解析和执行。6.4 让 Skill 调用外部 API以天气查询为例技能不光是本地脚本还可以主动调外部接口。比如写一个天气查询技能#!/bin/bash # run.sh - 查询指定城市天气 CITY$1 curl -s https://wttr.in/${CITY}?format3然后在 SKILL.md 里描述“查询天气时使用参数为城市名”。这样一个简单的 API 集成就完成了。更复杂的场景也是如此用户在对话中提出需求模型判断该用哪个技能技能脚本去调用 API拿回数据后再由模型整理成自然语言答案。这套机制就是“接入 API最不用写代码的方式。6.5 热加载改完技能不用重启我特别喜欢一个设计技能目录改动后OpenClaw 会自动加载不用重启服务。也就是说你写好一个技能、保存文件马上就能在对话里测试效果。这种实时迭代的方式让二次开发的效率高了很多。所以我不建议新手一开始就追求复杂的技能先从简单的 Shell 脚本开始跑通了再慢慢加功能。7. Active Memory长期记忆让OpenClaw记住你上次交代的事7.1 默认情况下OpenClaw 是“金鱼记忆”默认状态下OpenClaw 每次对话都是相对独立的上下文有限。你上周让它整理过一份资料今天再问它那件事它可能完全没有印象。这个问题靠模型本身没法解决需要靠外部记忆系统也就是 Active Memory。Active Memory 做的事情简单说就是把重要信息从对话中提取出来写入一个持久化的存储目录、SQLite 或向量数据库后续对话时再自动检索相关内容喂给模型。相当于给机器人加了一个“工作笔记本”。7.2 怎么开启和配置开启方式一般是在配置文件里指定记忆后端memory: backend: file path: ~/.openclaw/memorybackend可以是 file简单文本存储或其他数据库类型path是记忆文件的存放目录。设置完以后重启 OpenClaw就可以开始使用记忆功能。想让机器人记住某个信息直接在对话里说“请记住我的项目代号是 XX当前版本是 2.1”之类的话它会自己提取并存储。下次对话时如果你提到相关话题它会自动调取。7.3 高阶用法日常总结 自动归档我现在的习惯是每天结束前让 OpenClaw 把当天的工作内容整理成几条要点存进记忆库。长期下来它对我的项目背景、偏好、常用工具都越来越了解需要协作的时候不用反复交代前因后果。这种“持续工作记忆”的效果比每次开新会话都从零开始要高效得多。有一点要特别提醒记忆内容会不断累积所以过一段时间要做清理。另外不要往记忆里存密码、密钥之类的敏感信息因为记忆文件是明文存储的一旦泄露就是批量泄露。8. 安装使用中的高频报错一份可以直接照抄的排查清单8.1 总原则先看日志别猜装完 OpenClaw 以后遇到各种报错太正常了。我的排查原则永远是先看日志再翻配置最后才去搜社区。OpenClaw 启动后终端窗口会持续输出日志报错信息就混在里面。如果日志被刷屏了用调试模式重新启动OPENCLAW_LOG_LEVELdebug openclaw startdebug 模式会打印非常详细的执行信息报错原因基本都能定位到。8.2 “Control UI did not start”的两层排查思路这个报错通常是 Control UI 服务没有正常起起来。第一层检查端口占用lsof -i :3000Windows 上可以用netstat -ano | findstr :3000如果端口被别的进程占用了换一个端口启动很多版本支持--port参数。第二层检查浏览器访问的本地回环地址是否写对了有时候服务跑在 127.0.0.1你在浏览器里访问 localhost 却没走 IPv4也会打不开。8.3 “node runtime not found” 和 PATH 环境变量的倒霉问题报错信息类似oneclaw node runtime not found看着吓人其实核心就是系统找不到 Node.js。原因通常有两个Node 压根没装上或者装上了但 PATH 没刷新。Windows 用户装完 Node 以后之前的终端窗口不会自动更新 PATH必须新开一个窗口。如果新窗口还是找不到检查一下系统环境变量里有没有 Node 的安装目录没有就手动加。macOS 用户如果用的是 nvm 安装的 Node需要确认当前 shell 加载了 nvm 的初始化脚本否则新开的终端里也找不到 node这个问题在 zsh 里很常见。8.4 “EBUSY: resource busy or locked” 是 Windows 专属的痛报错里出现failed to remove ~\.openclaw: error: EBUSY: resource busy or locked, unlink我基本能在心里断定你用的是 Windows。这是文件被占用导致的常见于旧版本的 OpenClaw 进程还在后台运行或者杀毒软件正在扫描这个目录。解决办法分三步打开任务管理器找到所有 node 和 openclaw 相关进程结束掉。关掉杀毒软件的文件监控或者把~/.openclaw目录加入白名单。手动删除残留目录确认没有占用后再重新执行安装或初始化。8.5 “agent failed before producing a reply” 的模型连通性排查这个报错表示对话流程启动失败绝大多数情况下是模型配置有问题不是 OpenClaw 本体坏了。按这个顺序查API Key 是否有效、是否填错。baseURL 是否能正常访问浏览器直接打开看通不通。模型名是否精确匹配。账户余额是否充足。如果用本地模型确认 Ollama 服务已经启动而且模型已经拉取到本地。我自己的实测经验80% 以上的“agent failed”案例出在 API Key 无效和模型名不匹配这两个问题上所以优先查这两项。8.6 读取不了文档权限和解析依赖是重灾区OpenClaw 读取不了本地文档常见原因有三个文件路径不对或权限不足尤其放在系统受保护目录下的文件。文档格式不被支持比如某些 PDF 是扫描版图片没有文字层模型拿到手也无法解析。缺少对应的解析依赖比如读取 docx 需要相关的处理库没装。解决办法很简单先把文件放到一个普通权限目录比如~/Documents然后在对话里用绝对路径指定文件。如果还是不行把文档转成纯文本或 Markdown 再让它读成功率会高很多。最后说点个人感受。我用 OpenClaw 小半年最大的体会是别一上来就追求复杂技能和花哨玩法先跑通一个最小闭环再慢慢加料。装好以后的第一周我就只让它干两件事读文件、查资料等我把这两条链路用顺了才开始写自己的技能和接各种平台。这套项目最大的亮点是它的扩展性足够强skill 机制、记忆系统、多平台接入每个方向都值得单独深挖但地基还是基础安装和模型配置这部分折腾明白了后面会越用越顺手。另外一个小建议每次改配置文件之前先备份一份旧的哪怕只是复制到别的地方。OpenClaw 的配置看起来简单但改错一个缩进就能让你排查半小时备份是最廉价的保险。
OpenClaw 6分钟安装教程：从零跑通AI智能体框架
你们催的 OpenClaw 安装教程来了其实我早就想写了但一直觉得这玩意儿对小白不太友好直接扔一堆命令出去容易把人劝退。这次我把完整流程重新走了一遍从零开始、不看文档、不写代码把每一步卡住的地方都记录下来整理成了一套适合新手的操作路径。标题说 6 分钟安装是真的但前提是你把模型服务的 API Key 提前准备好不然卡在初始化环节别怪我。OpenClaw 这个名字圈子里玩过的应该都熟它其实就是之前的 Clawdbot一个开源的 AI 智能体框架。简单说它能让你用自然语言指挥 AI 去执行实际任务而不只是陪你聊天。写小说、读文档、调接口、定时跑脚本、挂在飞书群里当机器人这些都能干。这篇教程覆盖 Windows、macOS、Linux 三种环境装完以后跑不起来的直接翻到最后一节的报错排查手册对照着查。1. OpenClaw和Clawdbot到底是个什么东西别把它当成普通聊天机器人1.1 从Clawdbot改名到OpenClaw它解决了什么问题先说背景。Clawdbot 是早期项目名后来正式更名为 OpenClaw所以你在网上搜的时候两个名字对应的是同一个东西。我理解它是在做一个“AI 代理运行环境”你给模型一个目标它自己判断需要调用哪些工具然后一步步把任务做完。这个思路和普通聊天窗口完全不一样。传统聊天机器人是你一句它一句输出完就结束了上下文断了也不管。OpenClaw 的设计是它会带着任务去调度工具比如读写文件、执行命令、请求外部 API、搜索本地资料甚至通过消息平台和人对谈整个流程可以被编排成一套可复用的“技能”。早期版本里这个编排层叫 Harness社区里也有人拿它和 Hermes 之类的项目做对比本质上都是在解决“模型怎么在真实环境里稳定干活”的问题。1.2 它到底能干什么几个最常见的使用场景我实际用下来比较典型的使用场景有这几个挂到聊天群里做自动问答和群管把 OpenClaw 接进飞书、钉钉、微信生态的机器人群里有人提问它会调用文档或搜索工具来回答还能帮你收集回复内容。自动写小说并落盘通过自定义 skill让模型按照设定生成章节保存到本地目录不需要手动复制粘贴。读文档、整理摘要丢给它一份 PDF 或 Markdown它自己抽取内容、生成结构化摘要。定时任务和数据处理通过技能脚本定时抓取数据、处理表格、发通知相当于给自己配了个自动化助理。个人知识库问答配合 Active Memory 长期记忆让机器人记住你之前交代过的背景资料下次对话不用重复解释。1.3 它和“聊天机器人”最大的区别在哪里关键在于“执行闭环”。普通聊天模型只负责生成文本OpenClaw 在生成文本之外还负责执行动作、观察结果、修正方向。你可以把它理解成“模型有了手和脚”模型就像是大脑技能脚本是手文件系统和 API 是它可以操作的对象。对小白来说你不需要一开始就理解这整套机制。只需要知道安装完以后你可以在聊天界面用自然语言让它“帮我读一下当前目录下的 data.xlsx统计一下总金额”它会自己去调 Python 脚本、读文件、返回结果。这就是它的价值。2. 动手前两分钟系统、依赖和模型服务先确认到位2.1 硬件和操作系统要求先说结论Windows 10/11、macOS 12 以上、主流 Linux 发行版Ubuntu、Debian、CentOS 都试过都能跑。虚拟机也能装但如果你用 VM 跑建议给虚拟机至少 2 核 4G 内存否则启动会很慢云服务器我用的腾讯云轻量应用服务器2 核 2G 跑基础版没问题但如果你打算加载本地模型做离线推理内存至少 8G 起步否则模型加载那一刻基本卡死。Mac mini 用户我单独说一句Apple Silicon 芯片跑 Docker 部署很顺M 系列芯片对很多模型的推理有加速用 Docker 装 OpenClaw 是最省心的一条路。Windows 用户注意PowerShell 执行策略默认限制脚本运行第一次跑安装脚本时大概率会被拦后面我会写怎么处理。2.2 依赖环境Node.js、Git还有 Docker 选装OpenClaw 的运行环境主要依赖 Node.js目前要求 18 以上推荐 20 LTS 版本。Git 也要装因为很多技能包和扩展从仓库拉取没有 Git 会卡在依赖下载那一步。Docker 属于选装但如果你懒得折腾本地 Node 环境走容器化部署会省很多事。装完 Node 以后有个常见坑终端关闭再重开后node 命令找不到。这是 PATH 环境变量没有刷新的问题Windows 下特别常见。我一般建议装完以后完全退出终端重新开一个新的窗口再试node -v确认能输出版本号再往后走。2.3 模型服务选型远程 API 还是本地模型这一步非常关键因为安装过程需要你选一个模型服务。两种方案各有优劣我列个表格你直接照着选方案优点缺点推荐配置远程 APIDeepSeek、通义千问等速度快不需要好显卡按量付费需要联网注册账号拿 API Key填进配置本地模型Ollama Qwen/Llama 等免费、隐私好、可离线吃配置部署麻烦一些16G 内存起步推荐 32G如果你只是为了体验流程我用 DeepSeek 的远程 API 确实最省心。如果你有本地 RTX 显卡或者 Mac 的统一内存比较大那直接上 Ollama 跑 Qwen 系列也够用。有一点先提醒本地模型跑 OpenClaw 时模型加载完之后的响应速度取决于你的显存/内存带宽不要期望太高先用小尺寸模型做验证。3. 六分钟实操跑通从第一条命令到Control UI弹出3.1 第 1 分钟先检查环境别等报错才回头打开终端依次执行下面三条命令node -v git --version docker --version第一条必须能输出版本号比如 v20.11.1第二条确认 Git 已安装第三条如果没装 Docker 不影响后面流程只是 Docker 部署路径用不了。如果 node 命令找不到回到第 2.2 节处理 PATH 问题。这一步的耗时排在第一分钟是因为很多人跳过它直接装结果装到一半才报环境错误反而更浪费时间。3.2 第 2~3 分钟执行官方安装脚本OpenClaw 提供一键安装脚本Linux 和 macOS 在终端执行curl -fsSL https://openclaw.ai/install.sh | bashWindows 用户在 PowerShell 里执行irm https://openclaw.ai/install.ps1 | iex这里我必须强调一句不要无脑复制网上的命令。执行之前先去官方仓库或官网核对一下脚本地址是不是最新版本因为这类安装脚本经常更新。另外curl | bash这种操作会把远程脚本直接交给 shell 执行有一定风险稳妥的做法是先把脚本下载下来看一遍再跑尤其是涉及文件写入的操作。安装过程会拉取依赖耗时跟你网络情况有关一般一两分钟。看到类似 “OpenClaw installed successfully” 的输出就算成功了。Windows 如果提示 “无法加载文件...因为在此系统上禁止运行脚本”在 PowerShell 里执行Set-ExecutionPolicy -Scope CurrentUser RemoteSigned然后重新跑安装命令。3.3 第 4 分钟初始化配置填模型和 API Key安装完成后执行openclaw init这个命令会引导你选择模型服务商、填写 API Key、确认一些基础配置。它会自动生成配置文件路径在~/.openclaw/config.json或~/.openclaw/config.yaml取决于版本。如果你用的是 DeepSeek直接在提示符里选 deepseek然后把 API Key 粘贴进去就行。如果你用的是 Ollama 本地模型这里要注意init 向导里可能不会直接列出本地模型你需要手动编辑配置文件把模型名改成你通过ollama list能看到的名称比如qwen2.5:7b。这一步是很多人卡住的地方后面第 4 节我专门写配置细节。3.4 第 5~6 分钟启动服务、打开 Control UI、发第一条消息初始化完成以后执行openclaw start正常启动后终端会输出 Control UI 的地址通常是http://localhost:3000或者http://localhost:8080。在浏览器打开这个地址你会看到一个聊天界面。在聊天框输入一句简单的测试指令比如你好请介绍一下你自己并告诉我你当前使用的模型名。如果它能正常回复说明整条链路已经通了。整个流程顺利的话前后确实只要五六分钟前提是 API Key 有效、依赖环境没出问题。3.5 备用安装路径Docker 和云服务器说明不想污染本机环境的话Docker 部署更干净。确保 Docker 已经启动然后执行docker run -d --name openclaw -p 3000:3000 -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest注意先把宿主机~/.openclaw目录建好否则挂载目录权限容易出问题。mac mini 用户用这个方式最省事。云服务器部署时记得在服务器的安全组里面放行 Control UI 对应的端口否则本地浏览器访问不到。不过这里也提醒一句如果服务器没有加 HTTPS 或者访问控制直接暴露端口会有被扫的风险我一般建议只在本地跑或者用 SSH 隧道访问别直接裸奔到公网。4. 模型接入是最大的坑DeepSeek、通义和Ollama的配置模板4.1 配置文件到底长什么样安装完以后配置文件~/.openclaw/config.yaml里模型相关的核心字段大概是这样的model: provider: deepseek name: deepseek-chat apiKey: sk-xxxxxxxxxxxxxxxx baseURL: https://api.deepseek.com/v1不同版本的字段名可能有差异但核心逻辑都一样provider 指定服务商name 指定模型名称apiKey 是密钥baseURL 是 API 地址。OpenAI 格式的兼容接口几乎都是这套参数。很多报错都集中在 name 这个字段上。模型名必须和服务商提供的名称精确一致多一个字母、少一个横杠都不行。我见过太多人把deepseek-chat写成deepseek_chat或者把qwen2.5:7b写成qwen2.5-7b结果启动的时候报一堆奇怪错误。4.2 三个常见模型服务商的配置模板直接照着抄DeepSeekmodel: provider: deepseek name: deepseek-chat apiKey: sk-你的key baseURL: https://api.deepseek.com/v1通义千问DashScope 兼容模式model: provider: openai name: qwen-max apiKey: sk-你的key baseURL: https://dashscope.aliyuncs.com/compatible-mode/v1Ollama 本地模型model: provider: openai name: qwen2.5:7b apiKey: ollama baseURL: http://localhost:11434/v1Ollama 的 apiKey 随便填一个非空字符串就行因为它本地不校验。4.3 多模型切换不用来回改配置OpenClaw 支持配置多个模型在配置里以列表形式写出来然后通过环境变量或者在 init 里选择默认模型。大致结构是models: - name: deepseek-chat provider: deepseek apiKey: sk-xxx baseURL: https://api.deepseek.com/v1 - name: qwen2.5:7b provider: openai apiKey: ollama baseURL: http://localhost:11434/v1这样想切换的时候不用改文件在 Control UI 或启动参数里指定模型名就行。我自己习惯是一个付费模型做日常问答一个本地模型做隐私数据处理两条链路互不干扰。4.4 “unknown model”报错的真正原因和排查方法这是安装后出现频率最高的报错之一报错长这样agent failed before reply: unknown model: deepsee,oec-turbo看到这个报错先别慌原因基本只有一个配置里写的模型名模型服务商根本不认识。比如有人复制了某个演示文档里的模型名但那个模型命名可能是另一个平台的或者填 key 的时候格式错了导致配置没解析成功。排查方法按顺序做打开配置文件检查name是否和服务商文档一致。直接在浏览器访问服务的 API 文档页面确认模型名列表别凭记忆猜。本地测试接口连通性用 curl 直接发一个最小请求比如curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer sk-你的key看返回的 models 列表里有没有你填的名字。如果本地能通、OpenClaw 里不通十有八九是配置文件的缩进或格式问题打开配置检查引号、冒号、空格YAML 对这种缩进是非常敏感的。别小看这一步我观察过周围很多新手最后都卡在这里。5. 把OpenClaw接进飞书、钉钉和微信在聊天窗口里遥控AI5.1 平台接入的整体思路OpenClaw 本身不绑定任何聊天软件它通过连接器有些版本叫 channel 或 connector桥接到不同的 IM 平台。你在配置文件里加一段 channel 配置填入对应平台的机器人凭证它就能通过 Webhook 或长连接接收消息、回复消息。手机上的玩法也来自这里你不需要打开电脑上的 Control UI直接在聊天软件里发消息就能和它交互相当于把手机变成遥控器。5.2 飞书机器人配置最简单的一条路飞书接入的体验我觉得是三个里面最顺的。在开发者后台创建一个企业自建应用拿到 App ID 和 App Secret然后开启“机器人”能力在事件订阅里把 OpenClaw 的回调地址填进去。配置里大致加这一段channels: feishu: appId: cli_xxxxx appSecret: xxxxxx填完以后重启 OpenClaw去飞书里给你的机器人发一条消息试试。需要注意飞书的事件订阅要求回调地址必须是公网可访问的 HTTPS 地址内网环境下需要做内网穿透这一点要先想好。5.3 钉钉机器人配置要点钉钉的接入逻辑类似但钉钉更常用的是自定义机器人 Outgoing 机制。在钉钉群里添加自定义机器人设置 POST 回调地址并把加签密钥填到 OpenClaw 配置里。这样群里 机器人时OpenClaw 就能收到消息。钉钉有一点比较麻烦自定义机器人对消息格式要求比较严格单条消息有长度限制返回长文本时容易被截断。我实际使用中遇到回复比较长的情况会让 OpenClaw 先把内容写入文件或在线文档然后把链接返回给群聊体验会好很多。5.4 微信生态官方通道和个人号方案的风险差异微信是大家问得最多的但也是我建议要谨慎的地方。如果你是开发者优先考虑公众号或企业微信的官方机器人接口用微信官方提供的 API稳定且合规。个人微信号接入属于非官方方案市面上确实有一些协议库能实现但这类方案一直存在账号风控风险轻则功能被限制重则封号。我的个人建议是拿小号测试可以千万别把常用的工作微信号接进去也别用它跑重要业务。OpenClaw 社区里讨论的微信接入多数也是小号试玩。参与这类折腾前先看看官方机器人通道能不能满足需求能用官方就用官方。6. Skill技能接口从写小说到自定义API都能自己扩展6.1 Skill 到底是什么一个技能就是一个文件夹很多新手听到“Skill”会觉得很难其实它的本质就是一个约定格式的文件夹。OpenClaw 通过读取这个文件夹里的描述文件知道什么情况下该调用它然后执行里面的脚本。一个最小技能包的结构长这样my_skill/ SKILL.md run.shSKILL.md是给模型看的说明书描述这个技能是干什么的、参数是什么run.sh是给机器执行的动作脚本可以是 Shell、Python、JavaScript什么顺手用什么。6.2 SKILL.md 的写法关键是让模型看懂看一个最简单的示例--- name: get_time description: 获取当前时间和日期当用户询问“现在几点”或“今天几号”时使用。 parameters: - name: format description: 时间格式可选 short 或 full required: false --- 运行以下命令获取时间 bash run.sh {format}文件头部的 YAML 部分是对这个技能的元数据描述其中description最重要因为模型要根据它判断什么时候选这个技能。描述写得越具体模型选错的概率越低。6.3 实际案例给 OpenClaw 写一个“写小说”技能热词里有“openclaw 写小说”我就拿这个举例。假设你想让 OpenClaw 按提示词写小说章节并自动保存成文件技能包可以这样组织novel_writer/ SKILL.md write_novel.pywrite_novel.py接收两个参数小说标题和章节号调用模型接口生成内容然后保存到本地 novels 目录。SKILL.md 的描述部分这样写--- name: novel_writer description: 根据用户提供的小说主题生成章节内容并保存到本地文件当用户说“写小说”“生成章节”“继续写最新章节”时使用。 parameters: - name: topic description: 小说主题 required: true - name: chapter description: 章节号 required: false ---这样你在对话里说“用科幻主题写小说第三章”OpenClaw 就会调用这个技能。整个过程不需要你手动去 Model 接口调接口、写文件模型会自动完成参数解析和执行。6.4 让 Skill 调用外部 API以天气查询为例技能不光是本地脚本还可以主动调外部接口。比如写一个天气查询技能#!/bin/bash # run.sh - 查询指定城市天气 CITY$1 curl -s https://wttr.in/${CITY}?format3然后在 SKILL.md 里描述“查询天气时使用参数为城市名”。这样一个简单的 API 集成就完成了。更复杂的场景也是如此用户在对话中提出需求模型判断该用哪个技能技能脚本去调用 API拿回数据后再由模型整理成自然语言答案。这套机制就是“接入 API最不用写代码的方式。6.5 热加载改完技能不用重启我特别喜欢一个设计技能目录改动后OpenClaw 会自动加载不用重启服务。也就是说你写好一个技能、保存文件马上就能在对话里测试效果。这种实时迭代的方式让二次开发的效率高了很多。所以我不建议新手一开始就追求复杂的技能先从简单的 Shell 脚本开始跑通了再慢慢加功能。7. Active Memory长期记忆让OpenClaw记住你上次交代的事7.1 默认情况下OpenClaw 是“金鱼记忆”默认状态下OpenClaw 每次对话都是相对独立的上下文有限。你上周让它整理过一份资料今天再问它那件事它可能完全没有印象。这个问题靠模型本身没法解决需要靠外部记忆系统也就是 Active Memory。Active Memory 做的事情简单说就是把重要信息从对话中提取出来写入一个持久化的存储目录、SQLite 或向量数据库后续对话时再自动检索相关内容喂给模型。相当于给机器人加了一个“工作笔记本”。7.2 怎么开启和配置开启方式一般是在配置文件里指定记忆后端memory: backend: file path: ~/.openclaw/memorybackend可以是 file简单文本存储或其他数据库类型path是记忆文件的存放目录。设置完以后重启 OpenClaw就可以开始使用记忆功能。想让机器人记住某个信息直接在对话里说“请记住我的项目代号是 XX当前版本是 2.1”之类的话它会自己提取并存储。下次对话时如果你提到相关话题它会自动调取。7.3 高阶用法日常总结 自动归档我现在的习惯是每天结束前让 OpenClaw 把当天的工作内容整理成几条要点存进记忆库。长期下来它对我的项目背景、偏好、常用工具都越来越了解需要协作的时候不用反复交代前因后果。这种“持续工作记忆”的效果比每次开新会话都从零开始要高效得多。有一点要特别提醒记忆内容会不断累积所以过一段时间要做清理。另外不要往记忆里存密码、密钥之类的敏感信息因为记忆文件是明文存储的一旦泄露就是批量泄露。8. 安装使用中的高频报错一份可以直接照抄的排查清单8.1 总原则先看日志别猜装完 OpenClaw 以后遇到各种报错太正常了。我的排查原则永远是先看日志再翻配置最后才去搜社区。OpenClaw 启动后终端窗口会持续输出日志报错信息就混在里面。如果日志被刷屏了用调试模式重新启动OPENCLAW_LOG_LEVELdebug openclaw startdebug 模式会打印非常详细的执行信息报错原因基本都能定位到。8.2 “Control UI did not start”的两层排查思路这个报错通常是 Control UI 服务没有正常起起来。第一层检查端口占用lsof -i :3000Windows 上可以用netstat -ano | findstr :3000如果端口被别的进程占用了换一个端口启动很多版本支持--port参数。第二层检查浏览器访问的本地回环地址是否写对了有时候服务跑在 127.0.0.1你在浏览器里访问 localhost 却没走 IPv4也会打不开。8.3 “node runtime not found” 和 PATH 环境变量的倒霉问题报错信息类似oneclaw node runtime not found看着吓人其实核心就是系统找不到 Node.js。原因通常有两个Node 压根没装上或者装上了但 PATH 没刷新。Windows 用户装完 Node 以后之前的终端窗口不会自动更新 PATH必须新开一个窗口。如果新窗口还是找不到检查一下系统环境变量里有没有 Node 的安装目录没有就手动加。macOS 用户如果用的是 nvm 安装的 Node需要确认当前 shell 加载了 nvm 的初始化脚本否则新开的终端里也找不到 node这个问题在 zsh 里很常见。8.4 “EBUSY: resource busy or locked” 是 Windows 专属的痛报错里出现failed to remove ~\.openclaw: error: EBUSY: resource busy or locked, unlink我基本能在心里断定你用的是 Windows。这是文件被占用导致的常见于旧版本的 OpenClaw 进程还在后台运行或者杀毒软件正在扫描这个目录。解决办法分三步打开任务管理器找到所有 node 和 openclaw 相关进程结束掉。关掉杀毒软件的文件监控或者把~/.openclaw目录加入白名单。手动删除残留目录确认没有占用后再重新执行安装或初始化。8.5 “agent failed before producing a reply” 的模型连通性排查这个报错表示对话流程启动失败绝大多数情况下是模型配置有问题不是 OpenClaw 本体坏了。按这个顺序查API Key 是否有效、是否填错。baseURL 是否能正常访问浏览器直接打开看通不通。模型名是否精确匹配。账户余额是否充足。如果用本地模型确认 Ollama 服务已经启动而且模型已经拉取到本地。我自己的实测经验80% 以上的“agent failed”案例出在 API Key 无效和模型名不匹配这两个问题上所以优先查这两项。8.6 读取不了文档权限和解析依赖是重灾区OpenClaw 读取不了本地文档常见原因有三个文件路径不对或权限不足尤其放在系统受保护目录下的文件。文档格式不被支持比如某些 PDF 是扫描版图片没有文字层模型拿到手也无法解析。缺少对应的解析依赖比如读取 docx 需要相关的处理库没装。解决办法很简单先把文件放到一个普通权限目录比如~/Documents然后在对话里用绝对路径指定文件。如果还是不行把文档转成纯文本或 Markdown 再让它读成功率会高很多。最后说点个人感受。我用 OpenClaw 小半年最大的体会是别一上来就追求复杂技能和花哨玩法先跑通一个最小闭环再慢慢加料。装好以后的第一周我就只让它干两件事读文件、查资料等我把这两条链路用顺了才开始写自己的技能和接各种平台。这套项目最大的亮点是它的扩展性足够强skill 机制、记忆系统、多平台接入每个方向都值得单独深挖但地基还是基础安装和模型配置这部分折腾明白了后面会越用越顺手。另外一个小建议每次改配置文件之前先备份一份旧的哪怕只是复制到别的地方。OpenClaw 的配置看起来简单但改错一个缩进就能让你排查半小时备份是最廉价的保险。 
