最近问 OpenClawClawdbot安装的朋友特别多这个被大家叫“AI龙虾”的开源项目在 2026 年算是彻底火了。但正因为热度高网上的教程也鱼龙混杂要么把官方英文文档原封不动丢给你要么只甩一条命令然后就没了下文。这篇指南的目标很简单——让完全没有 Linux、Docker 基础的纯新手也能在 Windows 上把 OpenClaw 跑起来。我会把环境准备的每一步拆开讲主流程尽量压缩到 2 分钟内完成中间所有踩过的坑和排查思路都写出来。1. 为什么 OpenClaw 被叫“AI龙虾”先花一分钟搞懂它是什么1.1 OpenClaw、Clawdbot、AI龙虾三个名字如何对应很多人在社区里看到这三个词还以为是三个不同的项目其实指的完全是同一个东西。OpenClaw 是项目主名Clawdbot 是它的传统别名或者说机器人形态AI龙虾则是中文社区起的绰号。为什么叫龙虾因为 Claw 在英文里有“爪子、钳子”的意思而龙虾恰好是水生动物里钳子存在感最强的代表。所以“AI龙虾 OpenClaw Clawdbot”这个记忆方式很形象它就是一个用钳子夹住各种工具和 API 的 AI 助手。我第一次看到这个名字时也有点迷糊翻完文档才反应过来。OpenClaw 并不是某个大厂发布的商用闭源产品而是一个开源项目核心目标是把“大模型调用工具”这件事标准化。打一个简单的比方以前的 AI 更像一张只会聊天的嘴你说一句它回一句聊完就结束了OpenClaw 相当于给这张嘴装上了手和脚。通过一堆内置的适配器它可以自己去读写文件、调用网页 API、执行命令行命令、操作数据库甚至在自己的沙箱里运行代码。1.2 它到底解决什么问题AI Agent 框架这里必须多说一句因为“AI Agent”这个词已经被用烂了。市面上很多号称 Agent 的产品本质上只是一个套了壳的聊天窗口背后还是单纯的问答逻辑最多调一两个固定接口。OpenClaw 这类框架的做法不太一样它把 Agent 的核心循环做成了一套标准机制收到用户目标 → 把目标拆成子任务 → 从工具列表里选择合适工具 → 执行工具 → 观察返回结果 → 决定下一步操作 → 直到任务全部完成。也就是说装好 OpenClaw 之后你可以用自己的模型云端 API 或本地模型都行对它说“帮我扫描一下这个文件夹里的所有文本文件提取每个文件的大标题和三个关键句最后生成一份 Markdown 总览”。它会真的去遍历目录、逐个读取文件、调用大模型做提炼、再写出一份汇总文件而不是只给你一段“建议你手动操作”的废话。这就是它最近能成为 AI 自动化基建核心底座的原因。社区里有很多人讨论过像 WorkBuddy 这类后出的工具或多或少都参考了 OpenClaw 的设计思路时间线也对得上。1.3 谁适合看这篇指南如果你完全没碰过 Linux、Docker、命令行这篇文章就是给你写的。我会尽量把每一步说清楚甚至包括怎么看虚拟化有没有开启这种最基础的操作。如果你是想在 Windows 环境快速搭一个 AI 自动化服务的老手按这篇文章的部署方式也能省掉不少翻文档的时间。这里默认的环境组合是 Windows 11 WSL2 Docker Desktop这也是 OpenClaw 官方推荐度最高的组合。全篇以 Windows 为主但我会顺带提一下 Ubuntu 服务器上的安装差异。2. 安装前的软件清单WSL2、Docker Desktop、Node.js2.1 这三项基础软件各管什么事儿OpenClaw 不是一个单文件程序它跑起来之后会有一堆服务端组件协同工作后台监听消息、管理会话状态、调用大模型、执行沙箱任务。这些任务如果在 Windows 原生环境里跑来跑去会遇到文件路径不一致、进程权限混乱、端口占用难排查等一堆问题所以官方更建议放进 Linux 环境里跑。你在 Windows 上安装本质上就是通过 WSL2 开出一个轻量 Linux 虚拟机然后在虚拟机里运行 Docker 容器最后把容器端口映射到 Windows 来访问。WSL2 可以理解为“跟 Windows 深度集成的轻量虚拟机”专门用来在 Windows 下跑一个完整 Linux 内核。Docker Desktop 负责管理容器OpenClaw 启动后会按照编排文件拉取多个镜像比如主服务镜像、数据库镜像、沙箱环境镜像。Node.js 则是 OpenClaw 的命令行工具和 Windows Companion 的运行环境所以也必须装好。把这三样搞明白后续安装就会顺很多。2.2 Windows 环境配置实操按从底层到上层的顺序来安装顺序建议从底层开始一层一层往上先开 CPU 虚拟化再装 WSL2然后装 Docker Desktop最后装 Node.js。第一步检查 Windows 虚拟化是否开启。打开任务管理器切到“性能”标签点 CPU在右下角找到“虚拟化”这一项。如果是“已启用”万事大吉如果是“已禁用”需要重启电脑进 BIOS找到 Intel VT-x 或 AMD SVM 选项开启后保存退出。这一步不做的话后面 WSL2 百分之百会报错。第二步在“启用或关闭 Windows 功能”里把“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两项都勾选上然后重启。重启后以管理员身份打开 PowerShell依次执行这几条命令wsl --update wsl --set-default-version 2 wsl --statuswsl --update会把 WSL2 内核更新到最新版本。wsl --set-default-version 2表示后续创建的 Linux 发行版默认以 WSL2 模式运行。wsl --status则用来确认当前状态。如果输出里能看到默认版本为 2说明核心部分已经 OK。第三步下载安装 Docker Desktop。装完打开它的设置界面在 General 里确保勾选了 Use the WSL 2 based engine。这一步非常关键很多人装完 Docker 却一直被 OpenClaw 报错就是因为 Docker Desktop 还在用旧版 Hyper-V 后端或者兼容模式。然后在 Resources 里把内存调高一些建议至少分 4GB 给 WSL2 虚拟机否则跑起来容易 OOM。弄完后在终端里执行docker --version能正常输出版本号就说明 Docker 装好了。第四步安装 Node.js 的 LTS 版本直接从官网下载安装包即可也可以用 nvm 管理。装好后在 PowerShell 里执行node -v能输出 v20 左右的版本号就代表成功。这里有个常见误解很多人看到 AI 项目就以为要装 Python其实只要你的 OpenClaw 是通过 Docker 部署的宿主机上根本不需要 Python所有 Python 依赖都在容器内部。2.3 本地模型选哪个Ollama 加 Qwen2.5-3B如果你不想注册各类云端大模型 API又希望 OpenClaw 能真正跑起来我非常推荐先装一个 Ollama然后拉取 Qwen2.5-3B 模型。Qwen2.5-3B 的参数量虽然不大但胜在够轻、工具调用能力够用纯 CPU 机器也能勉强跑起来16GB 内存的电脑体验已经不错了。这个组合最大的好处是不产生任何按量 API 费用安装也不需要复杂配置。安装 Ollama 很简单去官网下载 Windows 安装包装好后直接在 PowerShell 里执行ollama run qwen2.5:3b它会自动下载模型并进入一个对话终端先跑通这一步再回过身来配置 OpenClaw 就顺理成章了。Ollama 默认监听本机的 11434 端口这个地址稍后要填进 OpenClaw 的环境变量里。如果你在 Linux 服务器上部署其实套路一样只是把 Ollama 的安装方式换成 Linux 安装脚本。3. 主流程安装克隆、配置、启动3.1 克隆官方仓库与目录结构说明环境准备好之后主流程确实很快。打开 WSL2 的 Ubuntu 终端先建立一个专门放项目的目录再把 OpenClaw 官方仓库克隆下来mkdir -p ~/projects cd ~/projects git clone OpenClaw官方仓库地址 cd openclaw仓库地址不要随便从第三方博客复制最稳妥的办法是打开 GitHub搜索 OpenClaw 或 Clawdbot认准官方组织账号。确认的标准可以看组织名、Star 数量以及仓库活跃度这样才能避开被人篡改过的分包。克隆完成后用ls -la看看目录内容你会看到几个核心文件docker-compose.yml负责编排所有服务.env.example是环境变量模板cli目录里是命令行工具skills目录用来放自定义技能。这些结构并不复杂但看懂之后会非常有帮助。3.2 环境变量配置模型地址、密钥与数据目录接下来需要创建自己的环境变量文件。官方提供的.env.example是模板复制一份为.env然后按需修改cp .env.example .env打开这个文件最核心的几项无非是模型提供方、API 地址、API 密钥、数据存放目录。如果你用 Ollama 跑 Qwen2.5-3B可以这样填MODEL_PROVIDERopenai_compatible OPENAI_API_BASEhttp://localhost:11434/v1 OPENAI_API_KEYollama MODEL_NAMEqwen2.5:3b DATA_DIR/srv/openclaw/data为什么 Ollama 这组配置里的 API Key 填ollama就行因为 Ollama 的 OpenAI 兼容接口不校验密钥你随便填一个非空字符串都能过。但注意如果你后面切换到云端 OpenAI 兼容服务这里的值就必须换成真实的 API Key。一个非常容易踩的坑是地址填法。OpenClaw 主服务运行在 Docker 容器里而 Ollama 跑在宿主机上也就是 WSL2 子系统里。Docker 容器内不能直接用宿主机视角的localhost去访问宿主机的服务。OpenClaw 的编排文件一般会做一层网络处理让容器内的localhost指到宿主机所以http://localhost:11434/v1通常有效。一旦发现模型连不上马上把地址改成http://host.docker.internal:11434/v1再试这个问题我在不同版本上都遇到过。3.3 启动服务Docker Compose 与 CLI 自检配置结束后在项目目录里执行docker compose up -d docker compose psup -d会在后台启动所有服务。第一次执行时会拉取镜像耗时长短完全取决于你的网络速度这和 OpenClaw 本身没关系。执行完docker compose ps如果看到各个容器的状态都是Up说明服务已经拉起来了。如果有Restarting或Exited就要往前排查。启动完成后再用 CLI 做一次自检./cli status如果能看到服务在线、模型连接正常那安装就已经完成了九成。这时候你可以直接在终端里对 OpenClaw 下达指令比如“告诉我当前系统时间”或者“列出当前目录下所有文件”它会通过工具去执行命令并返回结果。看到这一步跑通基本上就能确定你的 AI 龙虾已经正式上岗。4. 高频报错实战WSL2 检测失败、Docker 崩溃与模型连接问题4.1 “无法安全验证 WSL2 环境”的完整排查链路网络热词里有一条很典型的报错原文大概是“OpenClaw 无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status”。新手遇到这条提示很容易慌以为 OpenClaw 装坏了其实它只是检测不到一个能用的 WSL2 环境。这个报错一般有三个来源WSL2 内核没有更新、默认版本不是 2、WSL 里压根没装任何 Linux 发行版。排查手段非常直接先在 PowerShell 里执行wsl --status看输出里有没有“默认版本”和“内核版本”的信息。如果默认版本显示 1执行wsl --set-default-version 2。如果内核版本太旧或缺失执行wsl --update。如果这些都没有问题再执行wsl -l -v查看已安装发行版列表。列表为空的话用下面这条命令装一个 Ubuntuwsl --install -d Ubuntu装完再执行一次wsl --status然后重启电脑绝大多数情况下那个报错就会消失。整个过程不需要重装 OpenClaw因为问题根本不在 OpenClaw 这一层而是系统环境状态不一致。4.2 Docker Desktop 起不来时的几种真实原因第二个高频坑是 Docker Desktop 启动后一直转圈或者直接提示 Docker Engine stopped。最常见的原因是虚拟化没开这是最底层的硬伤前面已经说过要检查任务管理器里的虚拟化开关。第二个常见原因是 Windows 的虚拟机相关服务被禁用或没启动尤其是vmcompute服务。处理办法是打开“服务”管理界面找到“Hyper-V 主机计算服务”和“Windows 管理规范”把启动类型改为自动然后手动启动一次。第三个原因是电脑上装了旧版 Docker 或其他容器相关工具残留冲突导致新版本无法正常启动。这种问题没有太多捷径直接卸载 Docker Desktop同时清理%USERPROFILE%\.docker和%USERPROFILE%\AppData\Local\Docker这类残留目录再重装最新版。另外有朋友提到“安装 Docker Desktop 时一直没有出现 WSL2 后端选项”这通常是因为 Doker Desktop 安装时没有识别到 WSL2或者 Windows 版本太老。Windows 10 的 21H2 及以上版本才比较稳妥Windows 11 则完全没有问题。如果是 Windows 10 老版本先打系统补丁再重装 Docker。4.3 端口占用与本地模型连接失败OpenClaw 的某些端口是写死在默认编排文件里的比如常见的 16863、3000。如果本机已经有别的服务占了这些端口容器就会启动失败。判断方法很简单执行docker compose logs --tail50如果日志里出现address already in use那就是端口冲突。解决办法有两种一是把占用端口的其他程序停掉二是在.env里重新映射端口比如把宿主机侧的 3000 改成 3001。改端口比查谁占用了要快得多而且不影响功能。本地模型连接失败是另一类高频问题。表现为 OpenClaw 能启动但只要一问问题就报错日志里出现 connection refused 之类的字样。这种情况先不要动 OpenClaw单独测一下 Ollama 是否正常ollama list curl http://localhost:11434/v1/modelsOllama 正常的话问题基本可以锁定在容器与宿主机网络通信上。把.env里的模型地址改成http://host.docker.internal:11434/v1再重启服务90% 能解决。剩下那 10% 一般是防火墙拦截了 11434 端口放行即可。5. 进阶玩法关联 Qwen2.5-3B 并把 Skill 配好5.1 本地大模型接入 OpenClaw 的配置方式OpenClaw 的一大优点是不绑定任何特定厂商。你可以接 OpenAI、Anthropic、Google 的云端模型也可以接 Ollama、vLLM 等本地推理服务。接入本地模型的通用做法是把本地服务的地址配置成 OpenAI 兼容格式OpenClaw 直接按这个格式去请求就行。我实测下来qwen2.5:3b在 OpenClaw 里完全可用。但必须说清楚3B 参数的模型工具调用能力有限太复杂的任务它容易理解偏差比如把某个工具的参数填错。如果任务逻辑简单、步骤固定它完全能胜任如果你想要更强的自动化效果建议换 Qwen2.5 的 7B 或 14B 版本。选模型有一条硬性原则必须选支持工具调用或函数调用的模型纯聊天模型接进去只能聊天没法真正“动手干活”。5.2 写一个自定义 Skill 的完整示例Skill 是 OpenClaw 里非常实用的模块它的本质是提前给 AI 写好的“操作说明书”。我以一个查询 IP 地理信息的 Skill 为例展示它的结构。在skills/目录下新建一个子目录比如geo_query然后在里面放一个SKILL.md内容可以写成这样--- name: geo_query description: 查询指定IP地址的地理位置信息 tool: http_get parameter: {url: https://ipinfo.io/json} --- 用法当用户询问某个IP的位置时使用该Skill发送HTTP GET请求 把返回的JSON字段整理后回复用户。这里的关键是 front-matter 里的name、description、tool和parameter。tool: http_get表示使用 OpenClaw 内置的 HTTP 请求工具parameter是传给这个工具的默认参数。配置好之后重启一次 OpenClaw 服务它会自动扫描skills目录并加载技能。之后你对 AI 说“帮我查一下这个 IP 在哪”它就会根据描述匹配到对应工具并完成请求。实际上手写 Skill 时你会发现最难的不是语法而是怎么把“什么时候该用这个工具”描述清楚。描述越具体模型正确调用的概率就越高。官方仓库的skills目录里有很多现成例子我建议先照着改一个跑通再自己从零写。5.3 Windows Companion 的作用与配置思路热词里有人提到 OpenClaw Windows Companion这里简单补充一下它的定位。Companion 是运行在 Windows 宿主侧的辅助程序目的是把 Windows 的文件系统、剪贴板、音频输入等能力暴露给运行在 WSL2 内部的 OpenClaw 主服务。没有它AI 能操作的只有 WSL2 内部的 Linux 文件系统配置好之后AI 可以直接读写 Windows 下载目录里的文件甚至接管剪贴板。配置 Companion 其实不复杂先在 Windows 侧安装 Companion 程序把服务跑起来然后在 OpenClaw 的配置里填上 Windows 主机的通信地址。如果两边怎么都连不上优先排查 Windows 防火墙是否放行了对应端口。以我的经验来说Companion 属于那种“有需要再配”的组件如果你只是跑服务器用途或者所有操作都限定在 Linux 内部完全可以跳过这一项不影响核心使用。说实话我这个“2分钟零基础安装”的标题有点标题党的嫌疑——真正花时间的从来不是安装命令本身而是前期的环境准备和排错。但只要 WSL2、Docker Desktop、Node.js 这三样东西是干净完整的状态后面的主流程确实非常快。个人建议新手不要想着跳过环境检查直接跑命令省下来的几分钟最后往往都会在报错排查里加倍还回去。最后分享一个小经验如果哪天 OpenClaw 突然变得很慢别急着重装先看一眼docker compose logs --tail50和 Docker 的资源占用多半是日志堆积或内存不够清理容器日志、给 Docker 多分点内存就能解决。
最近问 OpenClawClawdbot安装的朋友特别多这个被大家叫“AI龙虾”的开源项目在 2026 年算是彻底火了。但正因为热度高网上的教程也鱼龙混杂要么把官方英文文档原封不动丢给你要么只甩一条命令然后就没了下文。这篇指南的目标很简单——让完全没有 Linux、Docker 基础的纯新手也能在 Windows 上把 OpenClaw 跑起来。我会把环境准备的每一步拆开讲主流程尽量压缩到 2 分钟内完成中间所有踩过的坑和排查思路都写出来。1. 为什么 OpenClaw 被叫“AI龙虾”先花一分钟搞懂它是什么1.1 OpenClaw、Clawdbot、AI龙虾三个名字如何对应很多人在社区里看到这三个词还以为是三个不同的项目其实指的完全是同一个东西。OpenClaw 是项目主名Clawdbot 是它的传统别名或者说机器人形态AI龙虾则是中文社区起的绰号。为什么叫龙虾因为 Claw 在英文里有“爪子、钳子”的意思而龙虾恰好是水生动物里钳子存在感最强的代表。所以“AI龙虾 OpenClaw Clawdbot”这个记忆方式很形象它就是一个用钳子夹住各种工具和 API 的 AI 助手。我第一次看到这个名字时也有点迷糊翻完文档才反应过来。OpenClaw 并不是某个大厂发布的商用闭源产品而是一个开源项目核心目标是把“大模型调用工具”这件事标准化。打一个简单的比方以前的 AI 更像一张只会聊天的嘴你说一句它回一句聊完就结束了OpenClaw 相当于给这张嘴装上了手和脚。通过一堆内置的适配器它可以自己去读写文件、调用网页 API、执行命令行命令、操作数据库甚至在自己的沙箱里运行代码。1.2 它到底解决什么问题AI Agent 框架这里必须多说一句因为“AI Agent”这个词已经被用烂了。市面上很多号称 Agent 的产品本质上只是一个套了壳的聊天窗口背后还是单纯的问答逻辑最多调一两个固定接口。OpenClaw 这类框架的做法不太一样它把 Agent 的核心循环做成了一套标准机制收到用户目标 → 把目标拆成子任务 → 从工具列表里选择合适工具 → 执行工具 → 观察返回结果 → 决定下一步操作 → 直到任务全部完成。也就是说装好 OpenClaw 之后你可以用自己的模型云端 API 或本地模型都行对它说“帮我扫描一下这个文件夹里的所有文本文件提取每个文件的大标题和三个关键句最后生成一份 Markdown 总览”。它会真的去遍历目录、逐个读取文件、调用大模型做提炼、再写出一份汇总文件而不是只给你一段“建议你手动操作”的废话。这就是它最近能成为 AI 自动化基建核心底座的原因。社区里有很多人讨论过像 WorkBuddy 这类后出的工具或多或少都参考了 OpenClaw 的设计思路时间线也对得上。1.3 谁适合看这篇指南如果你完全没碰过 Linux、Docker、命令行这篇文章就是给你写的。我会尽量把每一步说清楚甚至包括怎么看虚拟化有没有开启这种最基础的操作。如果你是想在 Windows 环境快速搭一个 AI 自动化服务的老手按这篇文章的部署方式也能省掉不少翻文档的时间。这里默认的环境组合是 Windows 11 WSL2 Docker Desktop这也是 OpenClaw 官方推荐度最高的组合。全篇以 Windows 为主但我会顺带提一下 Ubuntu 服务器上的安装差异。2. 安装前的软件清单WSL2、Docker Desktop、Node.js2.1 这三项基础软件各管什么事儿OpenClaw 不是一个单文件程序它跑起来之后会有一堆服务端组件协同工作后台监听消息、管理会话状态、调用大模型、执行沙箱任务。这些任务如果在 Windows 原生环境里跑来跑去会遇到文件路径不一致、进程权限混乱、端口占用难排查等一堆问题所以官方更建议放进 Linux 环境里跑。你在 Windows 上安装本质上就是通过 WSL2 开出一个轻量 Linux 虚拟机然后在虚拟机里运行 Docker 容器最后把容器端口映射到 Windows 来访问。WSL2 可以理解为“跟 Windows 深度集成的轻量虚拟机”专门用来在 Windows 下跑一个完整 Linux 内核。Docker Desktop 负责管理容器OpenClaw 启动后会按照编排文件拉取多个镜像比如主服务镜像、数据库镜像、沙箱环境镜像。Node.js 则是 OpenClaw 的命令行工具和 Windows Companion 的运行环境所以也必须装好。把这三样搞明白后续安装就会顺很多。2.2 Windows 环境配置实操按从底层到上层的顺序来安装顺序建议从底层开始一层一层往上先开 CPU 虚拟化再装 WSL2然后装 Docker Desktop最后装 Node.js。第一步检查 Windows 虚拟化是否开启。打开任务管理器切到“性能”标签点 CPU在右下角找到“虚拟化”这一项。如果是“已启用”万事大吉如果是“已禁用”需要重启电脑进 BIOS找到 Intel VT-x 或 AMD SVM 选项开启后保存退出。这一步不做的话后面 WSL2 百分之百会报错。第二步在“启用或关闭 Windows 功能”里把“适用于 Linux 的 Windows 子系统”和“虚拟机平台”这两项都勾选上然后重启。重启后以管理员身份打开 PowerShell依次执行这几条命令wsl --update wsl --set-default-version 2 wsl --statuswsl --update会把 WSL2 内核更新到最新版本。wsl --set-default-version 2表示后续创建的 Linux 发行版默认以 WSL2 模式运行。wsl --status则用来确认当前状态。如果输出里能看到默认版本为 2说明核心部分已经 OK。第三步下载安装 Docker Desktop。装完打开它的设置界面在 General 里确保勾选了 Use the WSL 2 based engine。这一步非常关键很多人装完 Docker 却一直被 OpenClaw 报错就是因为 Docker Desktop 还在用旧版 Hyper-V 后端或者兼容模式。然后在 Resources 里把内存调高一些建议至少分 4GB 给 WSL2 虚拟机否则跑起来容易 OOM。弄完后在终端里执行docker --version能正常输出版本号就说明 Docker 装好了。第四步安装 Node.js 的 LTS 版本直接从官网下载安装包即可也可以用 nvm 管理。装好后在 PowerShell 里执行node -v能输出 v20 左右的版本号就代表成功。这里有个常见误解很多人看到 AI 项目就以为要装 Python其实只要你的 OpenClaw 是通过 Docker 部署的宿主机上根本不需要 Python所有 Python 依赖都在容器内部。2.3 本地模型选哪个Ollama 加 Qwen2.5-3B如果你不想注册各类云端大模型 API又希望 OpenClaw 能真正跑起来我非常推荐先装一个 Ollama然后拉取 Qwen2.5-3B 模型。Qwen2.5-3B 的参数量虽然不大但胜在够轻、工具调用能力够用纯 CPU 机器也能勉强跑起来16GB 内存的电脑体验已经不错了。这个组合最大的好处是不产生任何按量 API 费用安装也不需要复杂配置。安装 Ollama 很简单去官网下载 Windows 安装包装好后直接在 PowerShell 里执行ollama run qwen2.5:3b它会自动下载模型并进入一个对话终端先跑通这一步再回过身来配置 OpenClaw 就顺理成章了。Ollama 默认监听本机的 11434 端口这个地址稍后要填进 OpenClaw 的环境变量里。如果你在 Linux 服务器上部署其实套路一样只是把 Ollama 的安装方式换成 Linux 安装脚本。3. 主流程安装克隆、配置、启动3.1 克隆官方仓库与目录结构说明环境准备好之后主流程确实很快。打开 WSL2 的 Ubuntu 终端先建立一个专门放项目的目录再把 OpenClaw 官方仓库克隆下来mkdir -p ~/projects cd ~/projects git clone OpenClaw官方仓库地址 cd openclaw仓库地址不要随便从第三方博客复制最稳妥的办法是打开 GitHub搜索 OpenClaw 或 Clawdbot认准官方组织账号。确认的标准可以看组织名、Star 数量以及仓库活跃度这样才能避开被人篡改过的分包。克隆完成后用ls -la看看目录内容你会看到几个核心文件docker-compose.yml负责编排所有服务.env.example是环境变量模板cli目录里是命令行工具skills目录用来放自定义技能。这些结构并不复杂但看懂之后会非常有帮助。3.2 环境变量配置模型地址、密钥与数据目录接下来需要创建自己的环境变量文件。官方提供的.env.example是模板复制一份为.env然后按需修改cp .env.example .env打开这个文件最核心的几项无非是模型提供方、API 地址、API 密钥、数据存放目录。如果你用 Ollama 跑 Qwen2.5-3B可以这样填MODEL_PROVIDERopenai_compatible OPENAI_API_BASEhttp://localhost:11434/v1 OPENAI_API_KEYollama MODEL_NAMEqwen2.5:3b DATA_DIR/srv/openclaw/data为什么 Ollama 这组配置里的 API Key 填ollama就行因为 Ollama 的 OpenAI 兼容接口不校验密钥你随便填一个非空字符串都能过。但注意如果你后面切换到云端 OpenAI 兼容服务这里的值就必须换成真实的 API Key。一个非常容易踩的坑是地址填法。OpenClaw 主服务运行在 Docker 容器里而 Ollama 跑在宿主机上也就是 WSL2 子系统里。Docker 容器内不能直接用宿主机视角的localhost去访问宿主机的服务。OpenClaw 的编排文件一般会做一层网络处理让容器内的localhost指到宿主机所以http://localhost:11434/v1通常有效。一旦发现模型连不上马上把地址改成http://host.docker.internal:11434/v1再试这个问题我在不同版本上都遇到过。3.3 启动服务Docker Compose 与 CLI 自检配置结束后在项目目录里执行docker compose up -d docker compose psup -d会在后台启动所有服务。第一次执行时会拉取镜像耗时长短完全取决于你的网络速度这和 OpenClaw 本身没关系。执行完docker compose ps如果看到各个容器的状态都是Up说明服务已经拉起来了。如果有Restarting或Exited就要往前排查。启动完成后再用 CLI 做一次自检./cli status如果能看到服务在线、模型连接正常那安装就已经完成了九成。这时候你可以直接在终端里对 OpenClaw 下达指令比如“告诉我当前系统时间”或者“列出当前目录下所有文件”它会通过工具去执行命令并返回结果。看到这一步跑通基本上就能确定你的 AI 龙虾已经正式上岗。4. 高频报错实战WSL2 检测失败、Docker 崩溃与模型连接问题4.1 “无法安全验证 WSL2 环境”的完整排查链路网络热词里有一条很典型的报错原文大概是“OpenClaw 无法安全验证 WSL2 环境。请在 PowerShell 中运行 wsl --status”。新手遇到这条提示很容易慌以为 OpenClaw 装坏了其实它只是检测不到一个能用的 WSL2 环境。这个报错一般有三个来源WSL2 内核没有更新、默认版本不是 2、WSL 里压根没装任何 Linux 发行版。排查手段非常直接先在 PowerShell 里执行wsl --status看输出里有没有“默认版本”和“内核版本”的信息。如果默认版本显示 1执行wsl --set-default-version 2。如果内核版本太旧或缺失执行wsl --update。如果这些都没有问题再执行wsl -l -v查看已安装发行版列表。列表为空的话用下面这条命令装一个 Ubuntuwsl --install -d Ubuntu装完再执行一次wsl --status然后重启电脑绝大多数情况下那个报错就会消失。整个过程不需要重装 OpenClaw因为问题根本不在 OpenClaw 这一层而是系统环境状态不一致。4.2 Docker Desktop 起不来时的几种真实原因第二个高频坑是 Docker Desktop 启动后一直转圈或者直接提示 Docker Engine stopped。最常见的原因是虚拟化没开这是最底层的硬伤前面已经说过要检查任务管理器里的虚拟化开关。第二个常见原因是 Windows 的虚拟机相关服务被禁用或没启动尤其是vmcompute服务。处理办法是打开“服务”管理界面找到“Hyper-V 主机计算服务”和“Windows 管理规范”把启动类型改为自动然后手动启动一次。第三个原因是电脑上装了旧版 Docker 或其他容器相关工具残留冲突导致新版本无法正常启动。这种问题没有太多捷径直接卸载 Docker Desktop同时清理%USERPROFILE%\.docker和%USERPROFILE%\AppData\Local\Docker这类残留目录再重装最新版。另外有朋友提到“安装 Docker Desktop 时一直没有出现 WSL2 后端选项”这通常是因为 Doker Desktop 安装时没有识别到 WSL2或者 Windows 版本太老。Windows 10 的 21H2 及以上版本才比较稳妥Windows 11 则完全没有问题。如果是 Windows 10 老版本先打系统补丁再重装 Docker。4.3 端口占用与本地模型连接失败OpenClaw 的某些端口是写死在默认编排文件里的比如常见的 16863、3000。如果本机已经有别的服务占了这些端口容器就会启动失败。判断方法很简单执行docker compose logs --tail50如果日志里出现address already in use那就是端口冲突。解决办法有两种一是把占用端口的其他程序停掉二是在.env里重新映射端口比如把宿主机侧的 3000 改成 3001。改端口比查谁占用了要快得多而且不影响功能。本地模型连接失败是另一类高频问题。表现为 OpenClaw 能启动但只要一问问题就报错日志里出现 connection refused 之类的字样。这种情况先不要动 OpenClaw单独测一下 Ollama 是否正常ollama list curl http://localhost:11434/v1/modelsOllama 正常的话问题基本可以锁定在容器与宿主机网络通信上。把.env里的模型地址改成http://host.docker.internal:11434/v1再重启服务90% 能解决。剩下那 10% 一般是防火墙拦截了 11434 端口放行即可。5. 进阶玩法关联 Qwen2.5-3B 并把 Skill 配好5.1 本地大模型接入 OpenClaw 的配置方式OpenClaw 的一大优点是不绑定任何特定厂商。你可以接 OpenAI、Anthropic、Google 的云端模型也可以接 Ollama、vLLM 等本地推理服务。接入本地模型的通用做法是把本地服务的地址配置成 OpenAI 兼容格式OpenClaw 直接按这个格式去请求就行。我实测下来qwen2.5:3b在 OpenClaw 里完全可用。但必须说清楚3B 参数的模型工具调用能力有限太复杂的任务它容易理解偏差比如把某个工具的参数填错。如果任务逻辑简单、步骤固定它完全能胜任如果你想要更强的自动化效果建议换 Qwen2.5 的 7B 或 14B 版本。选模型有一条硬性原则必须选支持工具调用或函数调用的模型纯聊天模型接进去只能聊天没法真正“动手干活”。5.2 写一个自定义 Skill 的完整示例Skill 是 OpenClaw 里非常实用的模块它的本质是提前给 AI 写好的“操作说明书”。我以一个查询 IP 地理信息的 Skill 为例展示它的结构。在skills/目录下新建一个子目录比如geo_query然后在里面放一个SKILL.md内容可以写成这样--- name: geo_query description: 查询指定IP地址的地理位置信息 tool: http_get parameter: {url: https://ipinfo.io/json} --- 用法当用户询问某个IP的位置时使用该Skill发送HTTP GET请求 把返回的JSON字段整理后回复用户。这里的关键是 front-matter 里的name、description、tool和parameter。tool: http_get表示使用 OpenClaw 内置的 HTTP 请求工具parameter是传给这个工具的默认参数。配置好之后重启一次 OpenClaw 服务它会自动扫描skills目录并加载技能。之后你对 AI 说“帮我查一下这个 IP 在哪”它就会根据描述匹配到对应工具并完成请求。实际上手写 Skill 时你会发现最难的不是语法而是怎么把“什么时候该用这个工具”描述清楚。描述越具体模型正确调用的概率就越高。官方仓库的skills目录里有很多现成例子我建议先照着改一个跑通再自己从零写。5.3 Windows Companion 的作用与配置思路热词里有人提到 OpenClaw Windows Companion这里简单补充一下它的定位。Companion 是运行在 Windows 宿主侧的辅助程序目的是把 Windows 的文件系统、剪贴板、音频输入等能力暴露给运行在 WSL2 内部的 OpenClaw 主服务。没有它AI 能操作的只有 WSL2 内部的 Linux 文件系统配置好之后AI 可以直接读写 Windows 下载目录里的文件甚至接管剪贴板。配置 Companion 其实不复杂先在 Windows 侧安装 Companion 程序把服务跑起来然后在 OpenClaw 的配置里填上 Windows 主机的通信地址。如果两边怎么都连不上优先排查 Windows 防火墙是否放行了对应端口。以我的经验来说Companion 属于那种“有需要再配”的组件如果你只是跑服务器用途或者所有操作都限定在 Linux 内部完全可以跳过这一项不影响核心使用。说实话我这个“2分钟零基础安装”的标题有点标题党的嫌疑——真正花时间的从来不是安装命令本身而是前期的环境准备和排错。但只要 WSL2、Docker Desktop、Node.js 这三样东西是干净完整的状态后面的主流程确实非常快。个人建议新手不要想着跳过环境检查直接跑命令省下来的几分钟最后往往都会在报错排查里加倍还回去。最后分享一个小经验如果哪天 OpenClaw 突然变得很慢别急着重装先看一眼docker compose logs --tail50和 Docker 的资源占用多半是日志堆积或内存不够清理容器日志、给 Docker 多分点内存就能解决。
