第一次知道 OpenClaw 这个项目是一个朋友跑来问我能不能在他的旧笔记本上跑起来我当时随口回了句“十分钟吧”结果自己回家折腾了快一个小时。后来复盘发现慢根本不在 OpenClaw 本身而是我踩了三个最常见的坑没提前确认 WSL2 环境、没搞懂“框架”和“模型”到底谁是谁、以及没意识到“部署完成”和“能正常对话”之间还差了一次正确配置。这篇保姆级教程就是把这些弯路重新捋直给你看零基础也能照着操作目标是在 7 分钟内看到对话窗口弹出第一句回复。我会默认你用的是 Windows 电脑也会单独讲 Linux 云服务器和 Docker 两条替代路线覆盖 OpenClawClawdbot部署、PowerShell 排错、Ollama 本地模型接入、Teams 与 Obsidian 联动等大家问得最多的问题内容比较长但每一步都是可以复现的。1. OpenClawClawdbot是什么先搞清楚再动手1.1 为什么有人叫它 Clawdbot有人叫它 OpenClawOpenClaw 是一个开源的 AI 助手框架早期项目名叫 Clawdbot后来项目改名成了 OpenClaw但很多早期教程、文档和讨论仍然在用旧名字所以你在搜索时经常会看到两者混用。中文社区因为名字里有个 Claw喜欢叫它“龙虾”你可以把它理解成一个可以自托管的 AI 智能体中枢用来接对话、调工具、管记忆、挂渠道而不是某一个具体的 AI 模型。这个区别很重要因为很多人第一次接触时会搞混以为装了 OpenClaw 就等于装了一个 Chat-GPT 那样的现成机器人。实际上 OpenClaw 提供的是“壳”和“接线板”真正负责生成回答的“大脑”是模型模型可以是云端的 OpenAI、Anthropic也可以是本地跑的 Ollama 私有模型。你部署 OpenClaw 的过程其实是在搭一套属于自己的 AI 助手底座。1.2 用之前先理解“框架”和“模型”的关系我用一个生活类比来帮你快速建立认知OpenClaw 相当于一台手机的操作系统而模型相当于系统里的语音助手应用。你换了不同品牌的助手应用手机本身还是那台手机同样你在 OpenClaw 里切换不同的模型供应商整套对话、工具调用、记忆管理的工作流并不会崩掉只是回答质量会变。这个设计带来的实际好处是日常简单问题可以用本地小模型便宜、隐私、离线也能用遇到复杂推理任务可以临时切到云端大模型。OpenClaw 的统一接口把这种切换成本压到了最低这也是我推荐大家入坑它的核心原因。部署前你只需要记住这条主线装 OpenClaw 是搭骨架配模型是装大脑联渠道是打通路。1.3 部署前必须搞定的三件事能不能装要看这三条在你准备开始第 1 分钟之前先花三十秒自检一下环境免得计时踩空一台能联网的电脑内存 8GB 以上。如果还打算跑本地模型尤其是 7B 以上参数的模型建议 16GB 起步。Windows 10 21H2 以上或 Windows 11并且确认自己用的是管理员账号。老版本系统装 WSL2 会非常痛苦有条件就直接上 Windows 11。一个可用的模型 API Key或者一台已经装好 Ollama 的机器。第一次部署我强烈建议先用云端 API 熟悉流程因为本地模型踩坑面更广容易打击信心。这三条满足后七分钟部署才真正有意义。如果你发现自己的 Windows 版本太老或者 BIOS 里虚拟化没开那么后面部署一定会卡住。这些前置问题会在第 3 章专门讲先记住结论环境对了部署本身就那么几步。2. Windows 电脑 7 分钟部署实操从零到第一条回复2.1 第 1 分钟检查并安装 WSL2说个实话OpenClaw 本身可以在 Windows 原生环境跑但它的部分系统组件比如文件监控、沙箱执行和部分工具链依赖真正的 Linux 内核环境所以官方在 Windows 上要求先准备 WSL2。这个环节 90% 的新手报错都出在这里千万别跳过。用管理员身份打开 PowerShell直接执行wsl --install这台机器如果之前没装过 WSL命令会自动安装“适用于 Linux 的 Windows 子系统”和默认发行版一般是 Ubuntu然后提示你重启。重启完成后再打开 PowerShell 执行wsl --set-default-version 2这条命令的意思是把默认 WSL 版本固定为 2因为我见过不少机器装完之后默认版本还是 1后续跑 OpenClaw 会莫名奇妙报环境错误。到这里第一分钟差不多用完楼下继续。2.2 第 2 分钟安装 Node.js 20 LTS 以上版本OpenClaw 的主体是 Node.js 写的所以你要装一个 Node 运行时。这里有一个我踩过的版本坑装老版本 Node 16 也能装上 OpenClaw但启动时会直接报语法错误因为新版代码用了不少 ES2022 特性。所以别贪省事直接装 20 LTS 或者 22 LTS。打开 Node.js 官网下载页面选 LTS 版本一路下一步装完。装完之后在 PowerShell 里验证node -v npm -v如果两条命令都有版本号输出说明安装成功。这里有个小经验如果你用的是 Windows 11直接winget install OpenJS.NodeJS.LTS也可以速度比去官网点鼠标快而且会自动配好环境变量。2.3 第 3~5 分钟安装 OpenClaw 并完成首次配置环境就绪之后主体安装其实就一条命令npm install -g openclaw-cli注意具体包名以你看到的官方仓库为准不同版本发布时可能略有调整。全局安装完执行初始化openclaw initinit命令会像问卷调查一样问你几个问题选择模型供应商、填写 API Key、设置数据存储路径。第一次配置时它生成的配置文件默认放在用户目录下文件名类似openclaw.config.json。我建议你把配置文件打开看一眼心里有个数后面接本地模型、接 Teams 都要改这个文件。到这一步三分多钟过去了OpenClaw 已经装好并完成基础配置。我见过很多人卡在这一步是不清楚 API Key 去哪里领这里统一说明OpenAI 类 Key 在对应平台的 API 管理页面创建注意它通常长这样sk-...长度不短如果你用的是本地 Ollama可以把 Key 这一项随便填个占位符因为本地模型不需要验证 Key这个细节在第 5 章展开讲。2.4 第 6~7 分钟启动、验证、再聊两句配置完成直接启动服务openclaw serve终端会显示监听地址一般是http://localhost:3000。浏览器打开这个地址应该能看到一个简单的对话页面。我建议你不要只满足于网页交互顺手在终端里试一下命令行模式openclaw chat输入一句“你好介绍一下你自己”如果它正常回复说明从框架到模型再到接口这一整条链路已经通透了。7 分钟计时到此结束。这里有个容易忽略的细节serve启动后的窗口不要关一关服务就停了。如果你想把 OpenClaw 长期挂在后台Windows 上可以用nohup思路的等价方案比如独立开一个窗口或者用 PM2npm install -g pm2 pm2 start openclaw -- serve用 PM2 的好处是开机自启、崩溃自动重启、日志集中几项都能覆盖比裸启动省心得多。3. PowerShell 专项排错那些让新手崩溃的报错到底在说什么3.1 “无法安全验证 SL2 环境”这句报错拆开看就不慌了很多人安装 OpenClaw 时会在 PowerShell 里遇到一条长报错大意是“无法安全验证 SL2 环境请在 PowerShell 中运行 wsl --status 后重试”。第一次看到这条消息的同学通常一脸懵SL2 是什么为什么装个软件还要安全验证SL2 指的就是 WSL2。OpenClaw 的安装脚本在 Windows 上有一个前置检查逻辑它要确认目标机器的 WSL2 环境真实可用然后用它来承载部分 Linux 依赖组件。这个“验证”不是要你的密码或凭证而是脚本内部调用了一个命令去查询 WSL 状态如果查询结果不符合预期就抛出这条错误。说白了问题不在 OpenClaw而在你机器上的 WSL 环境没准备好。3.2 wsl --status 的正确读法一行命令找出问题收到报错提示后先别急着重装 OpenClaw打开 PowerShell 执行wsl --status重点看两处如果是中文系统找“默认版本”这一项英文系统找Default Version。这个数字必须是2如果显示1说明 WSL 内核模式不对需要切换。再执行wsl --version这个命令能看到更详细的 WSL 版本信息正常输出里会包含“WSL 版本”和“内核版本”两行。如果两条命令都提示“未安装适用于 Linux 的 Windows 子系统”说明最开始的wsl --install没真正成功回到第 2.1 节重跑一遍重启后再检查。常见的修复动作我按优先级列一下切换默认版本wsl --set-default-version 2。如果提示需要更新内核去微软官方下载“WSL2 Linux 内核更新包”安装后重启 PowerShell。如果是老系统不支持需要在“启用或关闭 Windows 功能”里勾选“虚拟机平台”和“适用于 Linux 的 Windows 子系统”然后重启。进入 BIOS 确认虚拟化技术Intel VT-x 或 AMD-V已开启。这一步容易被忽略因为很多品牌机默认关闭虚拟化。做完以上任意一步后用wsl --status复验看到默认版本为 2再重新跑 OpenClaw 安装脚本就不会再报这条错了。3.3 其他高频报错清单与对应处理除了 SL2 问题我这里再贴一份我实际帮人排查时总结的高频报错对照表你可以直接对号入座报错特征根因处理方式安装时报语法错误提示 Unexpected tokenNode 版本过旧升级到 Node.js 20 LTS 或更高EACCES 权限不足Linux/macOS全局安装目录不可写使用 sudo 安装或改用 npx 方式运行启动时提示端口被占用3000 端口被其他服务占用改用openclaw serve --port 3001对话时收到模型鉴权失败API Key 填错或格式错误重新生成 Key并检查配置中是否多了引号或空格Ollama 连接不上baseUrl 填错或 Ollama 服务没启动确认ollama serve在运行且地址端口正确表格里最后一条“Ollama 连接不上”值得多说一句如果你把 OpenClaw 跑在 WSL 里而 Ollama 也跑在同一个 WSL 环境里那访问localhost:11434就是对的但如果你把 OpenClaw 跑在 Docker 容器里就要把地址改成http://host.docker.internal:11434否则容器内访问不到宿主机的 Ollama。这个“环境不同、地址不同”的问题是本地模型接入时最高频的翻车点。4. 不走 Windows 路云服务器与 Docker 部署方案4.1 阿里云免费试用实例上部署 OpenClaw没有 Windows 机器或者想 24 小时挂机的话云服务器是更优选。阿里云这类平台一般都有新用户免费试用轻量应用服务器的活动选择 2 核 2G 的配置就够了系统选 Ubuntu 22.04。服务器到手后先更新软件源并安装基础环境sudo apt update sudo apt upgrade -y sudo apt install -y git curl curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs然后再装 OpenClaw走一遍init配置。这里有一个和本机部署不太一样的点云服务器上你很可能想让它长时间后台运行我推荐用 systemd 托底。建一个服务文件sudo nano /etc/systemd/system/openclaw.service写入类似下面的内容[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Userubuntu WorkingDirectory/home/ubuntu ExecStart$(which openclaw) serve Restartalways [Install] WantedBymulti-user.target保存后执行sudo systemctl enable --now openclaw sudo systemctl status openclaw这套做法的好处是服务器重启后 OpenClaw 会自动拉起不用你手动登录敲命令。别忘了去云控制台的安全组配置里把 OpenClaw 监听的端口加入放行规则否则外部根本访问不到。4.2 Docker 方式部署一条命令解决的问题如果你已经用 Docker那部署就更简洁了拉镜像、起容器两步走docker pull ghcr.io/openclaw/openclaw:latest docker run -d \ --name openclaw \ -p 3000:3000 \ -v $(pwd)/openclaw-data:/data \ ghcr.io/openclaw/openclaw:latest冒号左边是宿主机端口右边是容器内端口。如果你宿主机上已经有别的服务占用了 3000可以把宿主机一侧改成 3001。-v参数把数据目录挂载到宿主机上这是为了防止容器重建时把配置和聊天记忆全部弄丢属于保命操作。Docker 方式最适合的场景是你要在一台机器上同时跑多个 AI 相关服务用容器隔离依赖互不干扰。我的建议是如果你不熟悉 Linux 和 systemdDocker Desktop 在 Windows 上也是个不错的选择只是它本身占用资源不算小只有 8G 内存的老机器会比较吃力。4.3 部署后的安全习惯别把密钥当儿戏不管走哪条路线有三个安全习惯我一直强调新手尤其要注意不要把 API Key 直接写在命令行参数里会被 shell 历史记录保存。正确做法是写入配置文件的独立字段并给配置文件设权限。云服务器上如果使用的是公共端口建议在安全组里限制来源 IP只允许你自己的办公网段访问。定期备份数据目录。OpenClaw 的配置、对话历史、长期记忆都在里面丢了之后会比重新部署难受得多。数据目录具体在哪里取决于你部署方式。本地装在用户目录下面Docker 容器里在你指定的挂载卷里。养成习惯备份一次就是一条 tar 命令的事别等哪天升级版本失败再后悔。5. 接入 Ollama 本地模型把 OpenClaw 变成离线智能助手5.1 为什么值得接本地模型云端模型省事但你会面临三个问题隐私、费用、网络依赖。如果你要把 OpenClaw 用在办公电脑上处理的内容不想经过第三方服务器或者你只是想省下每月的 API 账单那么接本地模型就是刚需。Ollama 是目前最省心的本地模型运行工具一键安装、命令行管理模型对新手友好到几乎没有门槛。配合 OpenClaw 之后你的整套助手就能在断网环境下直接对话响应速度只受本地硬件性能影响。当然也要清醒一点本地模型的“聪明程度”和云端旗舰模型有明显差距尤其体现在复杂推理、长文档理解和指令遵循上。本地模型的价值不是替代云端而是补足隐私和离线场景。我自己的用法是默认走本地小模型做日常问答遇到复杂任务临时切云端两者各管一摊。5.2 Qwen2.5-3B 接入 OpenClaw 的完整配置准备本地模型前先确认硬件能扛得住。Qwen2.5 3B 量化版大概需要 3~4GB 内存或显存6GB 显存的显卡就够用如果不走显卡只靠 CPU16GB 内存也能跑但速度会比较感人。第一步安装 Ollama。Windows 直接下载安装包Linux 执行curl -fsSL https://ollama.com/install.sh | sh第二步拉取模型ollama pull qwen2.5:3b拉取完可以先命令行验证一下ollama run qwen2.5:3b输入一句话看它是否能正常回复先排除模型本身的问题再接入 OpenClaw。第三步修改 OpenClaw 配置。在init生成的配置文件里把模型供应商改为 ollama 风格配置项大致如下{ model: { provider: ollama, baseUrl: http://localhost:11434, model: qwen2.5:3b, apiKey: ollama } }apiKey填ollama只是占位因为本地模型不做鉴权。改完配置重启openclaw serve再发一条消息测试。如果等了十几秒还没反应先单独确认 Ollama 有没有在运行再看 baseUrl 是否可达。5.3 资源不够时的降级方案和量力而行如果你的电脑跑 3B 都觉得吃力还有两条退路降级到更小的模型比如qwen2.5:1.5b甚至qwen2.5:0.5b出词速度快很多虽然“智商”下降但做关键词提取、格式化文本这类结构化任务完全够用。混合策略OpenClaw 配置里保留多个模型供应商简单任务用本地小模型复杂任务在对话中指定切到云端大模型。这种方式既能控制成本又能保证关键任务的回答质量。我的建议是新手先从云端 API 起步把 OpenClaw 的这套框架跑熟再逐步把本地模型加进来。直接上本地模型的话排错链路会拉长很多容易把第一次体验搞崩。6. 从“能对话”到“好用”Teams、Obsidian 和日常工作流6.1 接入 Microsoft Teams把助手放进团队协作里OpenClaw 支持把模型能力输出到 Teams 这类消息应用让它作为一个机器人成员待在你的工作频道里同事 一下就能提问。这个功能对团队内部知识库问答、会议纪要整理之类的场景非常实用。接入步骤大致分三块先在 Microsoft 的开发者平台里注册一个机器人应用拿到 Bot ID 和密码然后在 OpenClaw 配置里启用 Teams 通道填上对应的鉴权信息最后把消息回调地址指向你的 OpenClaw 服务指向格式一般是你的服务器地址加/teams路径。这里有两个实际提醒第一公司用 Microsoft 365 管理员统一管理的环境新应用的安装可能需要管理员审批提前沟通好第二本地部署时如果你没有公网地址Teams 的消息服务无法主动回调进来需要借助内网穿透或部署到云服务器这一步是团队场景下最容易卡住的地方。6.2 和 Obsidian 联动让笔记库变成助手的记忆库如果你是 Obsidian 用户OpenClaw 和它搭配起来很有意思。思路是把 Obsidian 的笔记库目录暴露给 OpenClaw让它能读取指定笔记内容然后再把回答写回新笔记形成一套“个人知识问答”工作流。最简单的落地方案是走 HTTP 接口Obsidian 社区有支持自定义 REST API 的插件你可以从笔记内容构造请求发给 OpenClaw让它总结、续写、翻译或抽关键词并生成新笔记。示例思路如下在 Obsidian 里选中一篇笔记。用插件里的自定义请求模板向http://localhost:3000/api/chat发一条包含笔记内容的 Prompt。返回结果后写回当前 Vault 里的一个新文件。没有现成插件的时候你也可以用命令行脚本替代只要会在终端里调 curl让 Obsidian 调用外部脚本即可。关键是理解这个模式OpenClaw 本身不用知道 Obsidian 是什么你只要把笔记内容发给它再把结果写回 Vault。6.3 我个人的使用经验与建议折腾 OpenClaw 大半年我现在的习惯很固定办公电脑上开一个 WSL2 环境跑 OpenClaw日常对话走 Ollama 里的 Qwen2.5 3B复杂一点的总结和代码走云端模型笔记长期积累在 Obsidian 库需要时用脚本把碎片笔记喂给 OpenClaw 整理成正式文档。Teams 机器人接入之后同事在群里问项目背景时不用再甩文档链接直接 助手就能拿到摘要。整个项目最让我感慨的一点是OpenClaw 解决的其实不是“有没有大模型可用”的问题而是“怎么让模型服务真正长在你的工作流里”。它像一个接线员把模型、对话界面、办公软件和笔记系统全部串起来。新手入坑时不要贪多先把一条链路跑通——Windows 部署、云端模型、网页或命令行走通一遍再来折腾本地模型和 Teams 联动。更多工具集成比如让它定期扫描某个文件夹、定时汇总网页内容都是在这个骨架上逐渐加出来的能力。按照这篇文章的步骤走完再结合你自己手头的高频场景去迭代你会比我更快找到最适合自己的用法。