如果你是因为“openclaw本地一键部署”这个热词点进来的估计你已经看过官方文档里那一长串 docker 命令了。不瞒你说我第一次看到的时候也有点头大环境变量、数据卷、端口映射、交互式命令行……对一个只想快点把东西跑起来的新手来说这些名词堆在一起很容易直接把人劝退。这篇就是系列里专门讲“本地一键部署”的那一章目标很明确让完全没接触过 Docker 的新手也能在自己电脑上把 OpenClaw 跑起来。先说清楚它到底是什么、能干什么。OpenClaw 是一个开源的个人 AI 助手项目通俗点讲就是给大语言模型接上“手脚”让它能根据你的指令处理日程、整理信息、执行自动化流程。本地一键部署的意思是不用买云服务器不用手动装一堆依赖只需要在你自己的电脑上执行一条命令镜像会把它运行所需的全部环境打包好、自动拉起来。这个方案最适合三类人不想折腾服务器的新手、对数据隐私比较敏感的人、想在本地快速验证这个项目到底好不好用的人。只要你的电脑满足基本要求照着下面的步骤走完大概率能在半小时内看到它跑起来。1. 为什么本地一键部署是新手把 OpenClaw 跑起来的最优解很多人在第一次接触这类项目时会在“本地部署”和“云服务器部署”之间犹豫很久。我的建议很简单如果你是新手而且只是自己想用、想学、想折腾先本地部署不要一上来就买服务器。原因不复杂我拆开讲。1.1 为什么把“本地”作为首选而不是直接上云云服务器部署听起来很“专业”但对新手来说它隐藏了大量额外的坑要选服务器配置、要配安全组、要管 SSH 密钥、要考虑带宽和流量费出了故障还得学会看远程日志。而本地部署最大的优势是把问题范围压缩到最小——所有东西都在你眼前这台电脑上报错了你直接查数据也都在本地磁盘里删了重建成本极低。我把两者做个对比你一看就明白对比维度本地一键部署云服务器部署硬件要求当前这台电脑就行需额外购买服务器金钱成本基本为零只需付 API 调用费服务器月租 流量费数据位置全部留在本地磁盘数据在云端需自行关注隐私故障排查本机看日志、看状态直观需要 SSH 登服务器门槛更高适合场景新手试水、学习原理、个人使用长期 7x24 运行、需要公网访问尤其重要的一点是本地部署对“试错”非常友好。你完全不用担心搞坏什么最坏的结果就是把容器删掉重新跑一遍。这种低成本的迭代方式恰恰是新手快速建立信心的关键。我第一次折腾这类项目时光在云服务器上配环境就花了一晚上后来换成本地部署十几分钟就跑通了那种挫败感和成就感之间的落差真的只有经历过才懂。1.2 一键部署对新手意味着什么更低的上手门槛为什么强调“一键”因为这个项目的运行依赖比你想象的多主程序、依赖库、配置环境、数据存储有时候还有内部的服务调度。如果走传统部署方式你需要手动安装编程语言运行时、逐条安装依赖、配置数据库、写启动脚本任何一个环节版本对不上都可能卡住大半天。而 Docker 镜像相当于把所有该装的、该配的东西全部提前打包进了一个“集装箱”。你在本地执行一条 docker run 命令其实就是把这个集装箱整体拉下来然后在电脑上启动一个隔离的运行环境。那些复杂的底层依赖关系镜像内部已经处理好了你不需要知道细节只需要把几个关键参数填对。这就是“本地一键部署”对新手最友好的地方它把部署过程从“学习一门系统管理课程”简化成了“填一张小申请表”。你需要理解的概念大概只需要四到五个后面会逐个讲到。1.3 什么人适合这个方案什么人不适合任何一个方案都有边界。我在推荐别人用本地一键部署之前一般会先问两个问题你是打算自己用还是打算给团队提供服务你是想跑起来玩玩还是想长期稳定运行如果你是想自己电脑上跑一个 AI 助手用来学习、测试、日常使用那本地一键部署完全够用。但如果你是想部署一个对外提供服务的系统要求 7x24 小时不宕机、多人同时访问、随时随地连接那还是得考虑服务器部署或者专业的托管方案。另外一个不太适合本地部署的场景是你的电脑配置太老内存常年不够用。OpenClaw 本身不算吃资源但 Docker Desktop 在后台会占用一部分内存建议至少 8GB 内存起步4GB 的机器跑起来会有点吃力。2. 部署前先弄明白一条命令背后究竟发生了什么很多人拿到一键部署命令之后直接复制粘贴就跑跑通了当然好但一旦报错就完全懵了。为了避免这种“黑盒式”的焦虑我建议你花十分钟理解一下这条命令的四个关键部分。不是要你变成 Docker 专家而是让你出问题时知道往哪个方向查。2.1 一条 docker run 命令拆开看其实就四件事以最通用的部署命令为例docker run -d \ --name openclaw \ -e OPENAI_API_KEY你的Key \ -e OPENAI_MODELgpt-4o-mini \ -v openclaw-data:/data \ ghcr.io/openclaw/openclaw:latest拆开来看无非四件事用什么镜像、给容器起什么名、往里塞什么配置、把数据存在哪里。参数作用新手容易忽略的点-d后台运行不占住当前终端不加的话关掉终端容器也会跟着停--name openclaw给容器命名方便后续管理名字重复会报错删掉旧容器再跑-e KEYvalue设置环境变量把 API Key、模型名等传进去Key 带空格或引号没转义是常见报错源-v openclaw-data:/data把容器内的数据目录映射到本地数据卷不加这个容器一删数据就没了最后一行镜像名指定要拉取的 Docker 镜像镜像 tag版本要确认存在这里要特别说明不同的 AI 项目、不同版本环境变量名、镜像名可能会略有差异。上面是 OpenAI 兼容接口的通用写法OpenClaw 项目的 README 里通常会给出对应的官方一键命令你直接用官方命令最稳妥。我在这里拆开讲是为了让你理解每一行是干什么的而不是让你死记硬背。2.2 环境变量、数据卷、镜像用大白话解释给新手听说几个生活化的类比帮助你在脑子里建立一个直观模型。Docker 镜像相当于一个“装了全部软件的装机 U 盘”。这个 U 盘里不光有操作系统还把 OpenClaw 需要的运行环境、依赖库、代码全部封装好了。你执行 docker pull就是把 U 盘里的内容下载到本地执行 docker run就是把 U 盘里的系统启动起来。容器是 U 盘系统启动之后正在运行的“那台电脑”。你可以启动多个容器彼此互不干扰。容器本身是临时的你把它删了系统就停了但 U 盘镜像还在随时可以重新启动一个新容器。环境变量相当于“启动系统时塞进去的小纸条”。程序启动时会读这些纸条知道该用哪个 API Key、调用哪个模型、连接哪个服务。这个设计的好处是同一个镜像可以给不同的人用大家只需要改自己的“纸条”不用改镜像本身。数据卷是“独立于系统盘之外的数据盘”。容器可以随时删掉重建但只要挂载了同一个数据卷里面的数据就还在。这非常关键因为 OpenClaw 运行时会产生配置文件、日志、记忆数据如果没挂数据卷容器一删你之前调好的东西就全没了。2.3 选哪家大模型 API 最省心环境变量与模型配置的逻辑OpenClaw 本身只是“骨架”真正负责理解和生成内容的是大模型 API。你需要先去一家大模型服务商那里申请一个 API Key然后把 Key 通过环境变量传给它。这里给你一个非常实用的建议优先选择你所在地区可以直接接入的大模型服务商比如智谱 GLM、通义千问、Moonshot 等。这些服务商大多提供 OpenAI 兼容接口意味着你只需要把环境变量里的 Base URL 换成服务商提供的地址再把模型名改成对应的模型 IDOpenClaw 就能正常调用。这种“OpenAI 兼容”设计是目前的主流做法A 平台的模型可以比较小代价地换成 B 平台的模型。配置逻辑其实不复杂一个环境变量负责告诉系统“你该访问哪个服务的接口”一个环境变量负责“你的身份凭证是什么”还有一个变量负责“你要调用哪个具体模型”。你把这三个信息填对剩下的就是系统自动处理的事情。申请 Key 的时候我提醒一句大多数平台的 Key 只在创建时完整显示一次一定要当时复制保存好关掉页面再想找只能重新生成一个新的。3. 从零开始跑通本地一键部署Windows 和 macOS 都能跟着做现在进入正题。我尽量把每一步都写到位你照着做就行。我按 Windows 和 macOS 两条线来说涉及区别的地方会单独标注。3.1 预备第一步安装 Docker Desktop 并确认它能跑起来Docker Desktop 是跑一键部署命令的基础环境。去官网下载对应你操作系统的稳定版建议不要下 Edge 版本稳定版出问题的概率低。安装过程基本是图形界面一路下一步但有三个细节很容易被忽略第一Windows 用户安装前先确认一下电脑的虚拟化功能是否已开启。打开任务管理器切到“性能”页签底部如果显示“虚拟化已启用”那就没问题如果显示“已禁用”需要先到 BIOS 里开启 Intel VT-x 或 AMD-V 选项否则后面装 WSL2 会一直报错。第二Windows 用户务必留意 WSL2 这个前置依赖。Docker Desktop 在 Windows 上默认通过 WSL2 运行安装过程中它会提示你启用相关功能。如果提示 WSL2 未安装需要先按官方指引安装 WSL 内核更新包然后在 PowerShell 里执行wsl --set-default-version 2确保默认版本是 2 而不是 1。我见过不少朋友卡在这一步原因就是 WSL 默认版本还是 1Docker Desktop 启动不了。第三macOS 用户要根据自己电脑的芯片选择对应版本。Apple Silicon 芯片的 Mac 下 Apple Silicon 版Intel 芯片的 Mac 下 Intel 版。安装完成后记得重启一次电脑这样 Docker Desktop 才能稳定初始化。重启之后启动 Docker Desktop屏幕右上角或菜单栏会出现一个小鲸鱼图标。第一次启动可能需要一两分钟初始化等图标不再跳动画、变成稳定状态说明引擎已经就绪。打开终端Windows 用 PowerShellmacOS 用终端输入docker --version如果能输出版本号说明环境准备好了。这一步看着简单但值得老老实实做一遍——很多人以为装完就万事大吉结果后面 docker 命令报错回头排查才发现 Docker Desktop 根本没启动。3.2 预备第二步申请 API Key注意“只显示一次”接着配置大模型 API。去你选定的服务商官网注册账号进入控制台或 API Key 管理页面创建一个新的 Key。这里有两个地方要特别上心一是创建时通常会让你选择模型权限或额度范围新手直接选默认的全面权限即可等用熟了再按需限制。二是创建成功后页面会显示一串以特定前缀开头的字符串这就是 API Key。它很可能只完整显示这一次赶紧复制到一个临时文件里保存好别直接发到聊天工具或公开仓库里。我之前有一次随手把 Key 贴进了一个 Markdown 笔记的公开仓库结果当天就被检测到异常调用只能作废重新生成白折腾了一下午。申请完之后最好先和服务商确认一下账户计费状态。绝大多数大模型 API 是预付或后付费模式如果账户没有开通计费即使 Key 有效调用时也可能报错。这一步虽然繁琐但真的能避免你后面花费大量时间排查“为什么一直报错”却找不到原因。3.3 执行一键部署命令以及首次启动的等待过程环境准备好了Key 也拿到手了现在开始正式部署。把前面示例命令里的占位符替换成实际值在终端里执行。注意如果你用的是项目 README 里的官方一键命令直接复制并替换占位符即可不同项目之间命令略有差异但整体思路一致。执行之后Docker 会开始拉取镜像。OpenClaw 的镜像体积通常在几百 MB 到 1GB 以上取决于包含的组件多少。第一次拉取需要一点耐心你可能会看到一段段进度条在刷新。这期间不要关闭终端也不要频繁按 CtrlC让它安安静静地下完。拉取完成后docker run 会自动创建并启动容器大概率不会再有更多输出你需要单独验证状态。这时候打开一个新终端输入docker ps如果看到 openclaw 对应的容器 STATUS 是 Up 状态说明容器已经起来了。接着看日志docker logs -f openclaw日志里如果出现类似“ready”“listening”“server started”之类的字样说明服务已经正常监听。看到这里一键部署的命令部分就算跑通了。我知道这个过程不算长但第一次跑通的瞬间确实有一种“原来也没那么难”的释然。4. 启动不算成功做完这三步验证才算真正部署好很多人看到容器状态是 Up 就欢呼“成功了”其实这只能说明进程活着不代表它能正常对话、能调用大模型。我习惯把验证分成三层逐层确认这样才能确定部署真的没问题。4.1 第一层验证容器状态和日志有没有告警第一层验证看的是“系统层面有没有问题”。先docker ps确认容器处于 Up 状态。注意看 STATUS 列如果后面有 “Restarting” 字样说明容器在反复重启这是异常信号。再看日志里有没有大量的 ERROR、WARN 级别输出。少量 WARN 通常不影响使用但 ERROR 基本都要处理。这里要说一个新手容易忽略的细节docker logs 是排查问题的第一入口但你不需要看完整日志用docker logs --tail 50 openclaw看最近几十行就行。大多数时候关键错误就藏在这个范围里。如果日志一直在刷新新内容可以先不加-f只看当前已输出的尾部避免被持续刷屏的信息干扰判断。4.2 第二层验证发起第一句对话确认端到端连通第二层验证是“功能层面”。容器在运行不等于模型连通了因为环境变量里的 API Key、模型名、接口地址如果有误服务可能照样启动只是在真正调用时会报错。怎么验证最简单的方式是直接进入容器运行项目自带的交互式命令或者通过项目提供的命令行客户端发起一条最简单的指令。比如docker exec -it openclaw bash进入容器后执行项目文档里给出的 CLI 入口命令比如openclaw chat或者openclaw run 你好具体以 README 为准。如果它能像正常聊天一样给出一段有意义的回复说明端到端链路是通的——容器没问题、API Key 配置正确、模型调用成功。这一步才是真正的“它活了”。如果你不习惯进容器操作另一种方式是通过项目暴露出来的交互界面。部分镜像会在启动日志里打印出一个本地访问地址用浏览器打开即可。用图形界面操作更直观但验证原理是一样的能成功发起对话才算部署完成。4.3 第三层验证重启之后配置还在吗第三层验证是“持久化层面”。一键部署最大的隐患不是跑不起来而是容器在重启或重建之后配置数据消失。OpenClaw 运行时会产生很多个性化配置比如你给它设定的角色、记忆、任务列表这些都需要持久化保存。先做一个小测试docker restart openclaw等几秒后看docker ps容器应该自动回到 Up 状态。再执行刚才的对话验证如果配置还在说明数据卷挂载生效了。更关键的是很多新手不知道容器的重启策略。Docker 默认情况下如果你重启了电脑Docker Desktop 会启动但容器不一定会自动跟着启动。你可以执行这条命令让容器每次开机都自动拉起docker update --restart unless-stopped openclaw这个细节在“本地一键部署”场景里极其实用。你不可能每次开机都手动跑一遍 docker start配置好这个策略之后它才会像一个真正的“本地助手”一样随开随用。5. 新手期避坑清单五个常见问题的完整排查过程最后这一部分是“价值密度”最高的地方。下面这些坑是我自己踩过、也看别人反反复复踩过的。我把每个问题的现象、排查步骤、解决动作和根本原因都写出来你遇到的时候直接按着这个思路走。5.1 坑一docker 命令连不上 Docker 引擎现象在终端执行 docker ps报错内容包含 “Cannot connect to the Docker daemon” 或 “error during connect”。第一次遇到的人通常会以为安装有问题甚至直接卸载重装其实大概率不是。排查过程先看 Docker Desktop 图标。如果是灰色的或者显示红色的错误状态说明引擎没有就绪。Windows 用户还需要检查 WSL2 状态是否正常可以打开 PowerShell 执行wsl --status看发行版是否 Running。macOS 用户则检查菜单栏的 Docker Desktop 是否已经启动。解决动作重启 Docker Desktop等待图标状态稳定再执行 docker ps。如果重启后仍然不行大概率是 WSL2 虚拟化问题回到 3.1 里说的 BIOS 虚拟化设置去排查。根因docker 命令本身只是一个客户端工具它需要连接后台引擎。你执行 docker ps 的时候实际上是客户端在向引擎发请求引擎没启动客户端自然连不上。5.2 坑二Windows 下 WSL2 反复报错现象Docker Desktop 安装完成后一直转圈或者提示 WSL2 未安装又或者启动后立刻提示 WSL 虚拟化失败。排查过程第一站是检查虚拟化是否开启。打开“任务管理器 → 性能 → CPU”看右下角“虚拟化”一栏。如果显示“已禁用”先去 BIOS 开启。第二站是确认 WSL2 内核版本在 PowerShell 里执行wsl --status如果提示内核版本太旧需要手动更新 WSL2 内核。解决动作BIOS 开启虚拟化后重启安装 WSL2 内核更新包在 PowerShell 里执行wsl --set-default-version 2。全部完成后再启动 Docker Desktop。根因Docker Desktop 在 Windows 上依赖 WSL2 提供的 Linux 子系统来运行容器而 WSL2 需要 CPU 虚拟化技术支持。这三者是一环扣一环的任何一环缺失都会导致启动失败。5.3 坑三容器启动即退出日志全是鉴权失败现象docker run 执行完毕但 docker ps 看不到容器在运行或者 STATUS 显示 Exited。查看日志里面有一堆 401、403、authentication failed 这类的报错。排查过程先看日志尾部提到的关键信息通常它会告诉你是在调用哪个 API 地址时鉴权失败。然后检查环境变量里的 API Key有没有带多余空格是不是整串都复制了创建 Key 之后是不是不小心改过解决动作重新生成一个 Key再次执行 docker run粘贴时注意不要带换行符和空格。如果用的是自定义服务商还要确认环境变量里的 Base URL 和模型名是否与该服务商提供的完全一致。根因鉴权 Key 传递失败或者传入的模型名不存在。这个问题最大的迷惑性在于容器本身没有“启动不了”的毛病它能起得来只是在尝试调用模型时被服务商拒绝了。所以遇到 Exited不要第一反应是“是不是镜像有问题”先看日志再说。5.4 坑四第一次拉取镜像进度卡住现象docker run 执行之后进度条长时间停在某个百分比不动或者显示连接中断。排查过程先想想是不是网络环境导致的。镜像体积通常不小下载需要稳定的网络。然后检查磁盘剩余空间——镜像下载会占用相当数量的磁盘空间磁盘满了会导致拉取失败。用df -hmacOS/Linux或资源管理器看一下剩余空间。解决动作如果进度卡住可以按 CtrlC 中途取消然后重新执行 docker run 或 docker pull。Docker 会存在断点续传机制重新执行不一定会从头开始。同时清一下磁盘空间确保有至少 10GB 余量。如果当前网络环境实在不稳定可以换一个网络比如手机热点再试一次。根因本质上是下载大文件时的网络问题或磁盘问题跟项目本身没关系。这类问题最忌讳一遍遍盲试而不看具体报错多观察一下卡在哪一步再针对性处理。5.5 坑五误删容器之后以为数据全没了现象执行了docker rm openclaw或docker rm -f openclaw然后重新运行了一个新容器结果发现之前配置的角色、记忆、任务列表全都不见了怀疑数据卷挂载失败。排查过程先别慌docker volume ls看一下本地的数据卷列表。如果看到 openclaw-data 还在说明数据其实没丢只是新容器没有正确挂载它。如果连数据卷列表里都没有那说明当初创建容器时可能漏掉了-v参数数据确实是没了。解决动作重新执行 docker run 时确保--name不跟现有容器重复同时-v openclaw-data:/data这个参数保持一致。数据卷本身独立于容器存在只要没手动docker volume rm删掉重新挂载就能恢复数据。根因容器和数据卷是两个生命周期完全不同的东西。容器可以随时重建数据卷负责在容器之外持久化数据。新手最常犯的错误是把“容器”当成了“数据本身”以为删掉容器就什么都没了其实数据和容器之间全靠那一个-v参数维系。最后分享一个我自己的小习惯遇到容器反复重启、启动即退出这类问题第一动作永远是docker logs而不是“删了重新跑”。日志会告诉你 90% 的答案盲目重来只是在赌运气。本地一键部署这个方案本身已经帮新手把复杂环境问题挡在了外面剩下要处理的基本就是 Key、参数、网络这几个变量。把这几个变量搞明白你就已经超过大多数刚接触这个项目的人了。
