OpenClaw 最近的热度确实离谱群里天天有人问怎么装、怎么配、为什么跑不起来。我前前后后帮朋友远程排查过好几轮从 Windows 到 Linux 到 WSL2 都踩过一遍踩坑记录都快攒成一本小册子了。这篇我就把整套搭建流程拆开揉碎从环境准备到模型接入再到常见报错处理一次性讲清楚保证你照着走能少走一大半弯路。这篇东西适合谁想在本机跑一个开源通用 Agent 的开发者、想给团队搭一个私有 AI 助手的人以及那些在 Windows 上折腾半天装不上 OpenClaw 的倒霉蛋。我会尽量把每一步的“为什么这么做”也说清楚而不是只丢一堆命令让你复制粘贴这样你后面自己排查问题时才有思路。1. 搭建前的整体思路与方案选型1.1 OpenClaw 到底解决什么问题先说结论OpenClaw 是一个开源的通用 AI 助手框架核心能力是让大模型不光能聊天还能真正“动手干活”——读写文件、执行命令、调用接口、操作浏览器甚至对接飞书这类办公协同平台把它当成团队的自动化工位。很多人拿它跟 Manus、WorkBuddy 这类产品对比。我的理解是WorkBuddy 更偏商业化的开箱即用工具而 OpenClaw 的好处在于全流程自托管数据留在自己的机器或服务器上配置灵活度高想接什么模型、想开几个 Channel、想让 Agent 掌握什么工具都由你自己说了算。对开发者和技术团队来说这种可定制性远比“开箱即用”四个字值钱。另外它用的是 Session 机制来管理多轮对话和任务状态每个任务对应一个独立的 Session 文件这样 Agent 可以长时间运行而不丢上下文。这个设计后面也会引出一些坑比如 Session 文件锁超时我在第 5 章会单独讲。1.2 环境选型Windows、WSL2 还是直接 LinuxOpenClaw 官方对 Linux 和 macOS 的支持最顺滑但现实是很多玩家主力机就是 Windows。我在实际帮人排查时发现绝大部分 Windows 下的安装失败案例根源都不是 OpenClaw 本身而是环境没配对。这里给一个明确的选型建议使用场景推荐环境原因主力是 Windows 且不想折腾WSL2 Ubuntu 22.04兼容性最好社区踩坑资料最多有一台 Linux 服务器/虚拟机纯 LinuxUbuntu/Debian最稳适合 7x24 小时挂机macOSIntel/Apple Silicon原生 macOS依赖基本都有照官方文档走即可Windows 老版本/虚拟机嵌套不推荐嵌套虚拟化问题多后面排查到你哭如果你只是想在 Windows 上随便试试也别倔直接上 WSL2 吧。热词里有人搜 “OpenClaw Windows Hub 安装”实际上你只要把 WSL2 弄好后面流程跟 Linux 版完全一致根本不需要什么特殊处理。1.3 模型后端选型为什么千问是个好选择OpenClaw 本身不带模型它需要接外部的大模型 API 来驱动 Agent。你可以接 OpenAI、Anthropic、本地 Ollama也可以接国产模型。热词里有人搜“OpenClaw 配置千问”我强烈建议国内用户优先考虑千问通义千问 Qwen。原因有三个国内直连延迟低稳定性好不用折腾网络环境Qwen 的 tool calling / function calling 能力在开源模型中属于第一梯队而 Agent 干活特别依赖这个能力API 价格相对友好日常跑任务成本低。我个人测试下来OpenClaw 接 Qwen-Turbo 跑常规任务完全够用复杂推理可以切到 Qwen-Max。后面第 4 章我会给出一份可以直接抄的配置。2. 环境准备与依赖安装2.1 Windows 用户先把 WSL2 收拾利索OpenClaw 在 Windows 上有两种玩法直接装在 Windows 原生环境或者装在 WSL2 里。我试过两种最终只推荐后者因为 OpenClaw 的诸多依赖Node.js 版本、Python 工具链、文件权限模型在 WSL2 的 Ubuntu 里表现更接近主流服务器环境出问题的概率低得多。第一步先确认 Windows 版本Win10 22H2 以上或 Win11 都行。然后以管理员身份打开 PowerShell执行wsl --install这条命令会自动启用 WSL 功能并安装 Ubuntu。装完之后重启电脑第一次启动 Ubuntu 会让你设置用户名和密码这个密码后面sudo要用别设完就忘。然后验证一下 WSL 版本确保是 2wsl -l -v如果看到版本是 1执行wsl --set-version 你发的发行版名字 2这一步可能会卡在“正在进行转换”如果超过 10 分钟没动静多半是 BIOS 里虚拟化没开去 BIOS 把 Intel VT-x / AMD-V 打开再执行一次。2.2 WSL2 内初始化基础环境进入 WSL2 终端后先把系统包和基础工具装上sudo apt update sudo apt upgrade -y sudo apt install -y git curl build-essential然后装 Node.js。OpenClaw 的运行时对 Node 版本有要求我用的是 20 LTS稳定没毛病。直接用 nvm 管理最省心curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新加载 shell 配置export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh然后nvm install 20 nvm use 20 node -v看到v20.x.x就说明 Node 环境搞定。这里提醒一句不要贪新装 Node 22 或 23OpenClaw 某些依赖在奇数版本和过新版本上可能有兼容性问题20 是最稳的。2.3 Linux 和 macOS 的准备要点如果你直接裸机 LinuxUbuntu 22.04 / Debian 12把上面的 apt 和 nvm 步骤照抄一遍就行。CentOS 用户建议尽早换到 Debian 系别跟自己的时间过不去。macOS 用户先确认装了 Homebrewbrew install git nodeApple Silicon 用户如果遇到node命令找不到检查一下是否安装了 Rosetta 转译层不过现在主流依赖都已经原生支持 arm64 了问题不大。2.4 准备模型 API Key在安装 OpenClaw 之前先把模型 API Key 准备好。以千问为例去阿里云百炼控制台创建一个 API Key记得开通模型服务。创建 Key 时有一个权限范围选项建议刚开始先用“默认业务空间”后面熟悉了再按需配置精细化权限。Key 创建好之后复制保存这个 Key 就是你 OpenClaw 与千问之间的通行证不要贴到公开仓库里。如果你还想接别的模型可以同时把对应的 API Key 也准备好后面配置的时候可以直接切换。3. OpenClaw 安装与初始化3.1 官方安装方式一条命令还是手动克隆OpenClaw 提供了一键安装脚本也支持从源码手动部署。我的建议是第一次安装用官方脚本等你想二次开发再手动拉源码。在 WSL2 / Linux 终端里执行curl -fsSL https://openclaw.example.com/install.sh | bash等等这个地址是我举例用的不要真的执行。正确的做法是去 OpenClaw 的 GitHub Releases 页面下载对应平台的安装包或安装脚本。开源的安装脚本一般会做这几件事下载 OpenClaw 主程序二进制或源码创建默认配置目录通常是~/.openclaw/写入系统服务配置可选初始化全局命令openclaw。安装完成后验证openclaw --version如果能正常输出版本号安装这步就算过了。如果提示command not found通常是安装脚本没有把可执行文件路径加到PATH里手动加一下就好export PATH$HOME/.openclaw/bin:$PATH然后把它写进~/.bashrc或~/.zshrc防止下次重启失效。3.2 首次启动与配置目录结构装完先别急着配模型先启动一次让 OpenClaw 生成默认配置openclaw init运行之后会在~/.openclaw/下生成一系列文件和目录常见的结构大概是这样~/.openclaw/ ├── config.yaml # 主配置 ├── channels/ # Channel 相关配置 │ └── feishu.yaml # 飞书 Channel 示例 ├── sessions/ # 会话文件存储目录 ├── logs/ # 运行日志 └── tools/ # 工具插件这个init命令只做初始化不会真的拉起服务。到这一步OpenClaw 的本体已经装好了接下来要把它“喂饱”——接入模型和 Channel。3.3 Channel 是什么怎么选OpenClaw 的 “Channel” 指的是它跟外部世界交互的通道你可以理解为它暴露给用户的“聊天入口”。我用过的常见 Channel 有CLI Channel直接在终端里跟 Agent 对话最基础适合调试飞书 Channel把 Agent 变成一个飞书机器人团队成员在飞书里直接跟它交互Web ChannelOpenClaw 自带一个 Web 界面方便多设备访问Telegram / Slack 等海外常用国内意义不大。热词里有人问“OpenClaw agent 怎么选择 channel”其实就是在config.yaml里指定channels字段或者在初始化的时候用交互式命令行选择。我的建议是第一轮先启动 CLI Channel确认 Agent 能正常说话、能调用工具再考虑接飞书等外部平台。一上来就配多个 Channel出了问题你都不知道是模型的问题还是通道的问题。4. 核心配置与模型接入4.1 修改配置文件接上千问打开~/.openclaw/config.yaml核心要改的字段是模型相关配置。下面是一份我实测可用的千问接入配置# config.yaml 关键片段 agent: name: openclaw-worker model: provider: qwen api_key: sk-你的千问APIKey model: qwen-plus base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 temperature: 0.7 max_tokens: 4096几个字段说明一下provider: qwen表示走千问的 OpenAI 兼容接口base_url是必须填的指向千问的兼容模式端点model可以填qwen-turbo、qwen-plus、qwen-max按任务复杂度选temperature控制随机性写代码类的任务我建议调低到 0.3创意写作类再调高。改完配置之后别急着找启动命令先用openclaw doctor或openclaw check这种诊断命令检查一遍配置是否有语法错误不同版本命令名略有差异用openclaw --help看一下。4.2 启动 CLI 模式测试 Agent检查没问题后先以交互模式启动openclaw run --channel cli如果看到类似Agent is ready, chat with exit to quit的提示说明 OpenClaw 已经跟千问握手成功。这时候你可以问一些测试题来验证 tool calling 能力比如帮我创建一个名为 test.md 的文件内容写“OpenClaw 环境测试成功”然后把它放到当前目录下。如果 Agent 真的创建了文件说明工具调用链路是通的这比单纯“能聊天”重要得多。这里有个小经验第一次测试尽量选一个能明确验证结果的任务比如“列出当前目录文件”“创建文件”“计算 2 的 10 次方并写进文件”不要上来就让它“分析一下今天的天气”因为你还没配天气工具它要么报错要么胡乱编。4.3 配置飞书 Channel 与“输出截断”问题预告接飞书是很多团队的需求毕竟大家日常都在飞书里办公。把 OpenClaw 接入飞书核心步骤是在飞书开放平台创建一个企业自建应用开启机器人能力拿到 App ID 和 App Secret在事件订阅里配置请求地址指向 OpenClaw 的 Web 回调端口在 OpenClaw 的channels/feishu.yaml里填上应用凭证、加密密钥和回调路径。config.yaml里启用飞书 Channelchannels: - type: feishu app_id: cli_xxx app_secret: 你的AppSecret encrypt_key: 你的EncryptKey verify_token: 你的VerificationToken port: 9000配置完重启 OpenClawopenclaw restart飞书 Channel 有一个特别常见的坑长输出被截断。热词里那句“OpenClaw 在飞书输出容易被截断”我深有体会。原因有两个层面飞书机器人单条消息有长度限制超过几千字就要分片发送OpenClaw 默认的消息分片逻辑是按固定长度切割的切到一半如果刚好碰上一段代码或表格就会显示得很乱甚至直接被飞书丢包。解决办法是给 Channel 配置开启自动分片和 Markdown 富文本模式channels: - type: feishu ... message_split: true split_strategy: paragraph message_format: markdownsplit_strategy设为paragraph表示按段落切分而不是按字符数硬切这样至少不会把语义切碎。另外如果你发现飞书里 Agent 回复内容不完整去 OpenClaw 日志里搜truncated或message too long关键词能精确定位是哪条消息被截了。5. 常见问题与排查实录5.1 WSL2 环境校验失败could not safely verify the WSL2 environment这是 Windows 用户安装时最常撞到的一堵墙。报错信息类似could not safely verify the WSL2 environment.我第一次看到这行字时也是一脸懵。排查下来这个报错的本质是OpenClaw 的安装脚本或者运行时会检查当前是不是跑在 WSL2 里它怕你在 WSL1 或虚拟化不完整的环境里运行导致后续各种诡异问题。常见的触发原因和解决办法原因表现解决办法WSL 内核太老wsl -l -v显示版本 1执行wsl --set-version name 2升级Windows 未开启虚拟机平台Hyper-V 相关功能关闭以管理员运行 PowerShell执行Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform重启WSL 内核损坏wsl --update失败到微软官网手动下载并安装 WSL2 内核更新包在“嵌套虚拟化”环境安装虚拟机里再跑 WSL2宿主机需开启嵌套虚拟化云服务器基本无解如果以上都排查过了还是报同样的错可以用一个绕行的方案放弃 WSL2直接装 Linux 版到虚拟机里或者用一台 Linux 云主机跑。反正 OpenClaw 是跨平台的把服务跑稳才是第一目标。5.2 Agent failed before reply: session file locked (timeout 60000ms)这个报错我见过无数次了报错原文是agent failed before reply: session file locked (timeout 60000ms)先说结论这个报错跟模型没关系跟任务卡死有关系。OpenClaw 的 Session 机制是每个会话对应一个文件Agent 在处理一次请求时会给这个文件加锁防止并发写导致数据损坏。正常情况下锁来得快去得也快但如果你让 Agent 执行一个特别耗时的任务比如让它爬一个大型网站、跑一个 10 分钟的视频处理命令锁的持有时间就会超过 60 秒然后其它请求进来就直接超时报错。解决办法有几个方向把单次执行的超时时间调大。在配置里加agent: session: lock_timeout: 300000单位是毫秒这里是 5 分钟。检查是否有残留的锁文件。如果 Agent 运行中崩溃或者你用 CtrlC 强杀过进程锁文件可能没被正常释放。去~/.openclaw/sessions/目录下找.lock后缀文件确认没有进程占用后手动删掉ls -la ~/.openclaw/sessions/ find ~/.openclaw/sessions/ -name *.lock -delete还有就是别发起并发任务。CLI 模式下一个会话只处理一个请求你如果开多个终端同时对同一个 Session 发消息必现这个锁超时。5.3 飞书消息截断的深层排查前面提过飞书截断有两种常见原因我再补充一条更隐蔽的飞书自定义机器人的消息回调有超时限制。OpenClaw 在飞书里被触发后需要等模型生成完回复再推给飞书。如果你用的模型是 qwen-max思考时间稍微长一点飞书那边可能已经等不及直接给用户回了一条“超时请重试”而 OpenClaw 这边还在慢慢生成等你把结果推过去时飞书的回调窗口早就关了。遇到这种情况我的建议是把飞书 Channel 的回复模式改成“异步推送”也就是收到消息后立刻回一个“正在处理中”等结果出来后再主动推送给用户而不是让飞书一直阻塞等待。具体配置项因版本而异通常叫async_reply或deferred_response开启后超时问题基本消失。另外给长输出配一个稳定的通道也很重要。如果你让 Agent 一次性生成一篇万字长文直接推到飞书群里对方很难阅读。我一般会让 Agent 把冗长内容写成 Markdown 文件再在飞书里回一个文件链接这样又清晰又不会触发截断。5.4 其它容易踩的坑再列几个我遇到过的杂项问题端口被占用飞书 Channel 默认监听 9000 端口如果这个端口已经跑着别的服务回调请求就过不来。换一个端口或者在启动命令里指定openclaw run --channel feishu --port 9001Node 版本不对前面强调过 Node 20 最稳有些人用 nvm 切到 21 或 18OpenClaw 装不上依赖。把node -v打印结果跟官方要求的对照一下版本不对就别硬抗。千问 API 返回 401检查api_key字段前面有没有多余的引号或空格再检查 Key 是不是复制完整了。Agent 不干活只会聊天很可能是模型不支持 tool calling或者配置里没开工具。在config.yaml里确认agent: tools: enabled: true然后重启再问它一句“你能使用哪些工具”看它怎么回答。6. 关于从源码部署和二次开发如果你想在 OpenClaw 上做二次开发比如自定义工具、改 Agent 的行为逻辑那就不能只靠安装脚本了得从源码跑。流程不复杂核心是把仓库克隆下来装依赖git clone https://github.com/openclaw/openclaw.git cd openclaw npm install npm run dev源码方式的主要优势是可以打断点调试、改代码热重载而且能直接看它的工具调用逻辑是怎么实现的。我建议对 Agent 开发感兴趣的读者都走一遍源码流程哪怕不写代码光看日志和源码都比看文档理解得深。从源码跑起来之后同样会读取~/.openclaw/config.yaml所以上一步的模型配置可以直接复用不需要重配。另外手动改源码有一个注意点每次从远程拉新代码前先备份你自己改过的文件。这玩意儿更新频率挺高我吃过一次亏改了一半的配置文件被git pull覆盖了前功尽弃。7. 我的一些私人建议聊几个踩过几轮坑之后才明白过来的点供你参考。第一OpenClaw 这类 Agent 框架的调试思路跟传统软件不太一样。传统软件出 bug你查代码、查日志总能找到根因但 Agent 框架里模型本身的随机性会带来各种“幽灵行为”——同一个配置这次能跑通下次就可能跑出一个你没见过的报错。所以排查问题时先别急着改代码先多跑几遍复现一下确认是稳定复现还是偶发。偶发问题大概率跟模型输出有关稳定问题才值得去查配置和代码。第二接千问的时候温度参数一定要调。Agent 干活需要的是稳定输出而不是天马行空的创意。我在测试时发现temperature从默认值调到 0.3 之后Agent 写代码时出语法错误的概率明显下降工具调用也更准确。你如果发现 Agent 经常“答非所问”先看看是不是温度太高。第三Session 文件是本地资产要养成备份的习惯。因为所有对话历史都存在~/.openclaw/sessions/里删了就等于失忆。我有一次清理磁盘时手抖把整个.openclaw目录删了结果所有历史会话都没了重新训练 Agent 的记忆花了半天。你要做的是定期把sessions目录备份到另一个存储位置tar -czf openclaw_backup.tar.gz ~/.openclaw/sessions第四OpenClaw 的日志是你的第一排查武器。很多人遇到问题就在群里问“为什么报错”但如果你先打开日志看一眼大多数问题自己都能定位。日志默认在~/.openclaw/logs/启动服务后保持一个终端开着tail -ftail -f ~/.openclaw/logs/agent.log这样 Agent 每一步干了什么、调用模型成功没有、工具返回什么结果全都在屏幕上滚排查效率至少翻一倍。最后再分享一个小技巧善用 CtrlD 或/exit正常退出 CLI别直接关终端。强制杀掉进程偶尔会导致 Session 文件写不完整下次启动报一些莫名其妙的校验错误。虽然重启能自愈但能避免就避免。OpenClaw 这套东西本质上是让你掌握一个能听指挥、能动手的 AI 助理中间有不少细节需要跟自己的使用场景磨合。刚开始装不上、跑不通都很正常按我上面写的流程一步步来先把最小可用跑通再逐渐加复杂度。等你能让它老老实实写文件、调接口、群里回答问题的时候回头看这些坑全都值得。