OpenClaw 在自托管 AI 圈子里讨论度不低配合 Docker Compose 部署和开发者模式可以让这个开源 AI 助手真正拿到“完全系统权限”——不是只在对话框里陪聊的玩具而是能直接操作你机器、执行真实任务的数字员工。这篇文章是我自己从零到一部署 OpenClaw 的完整复盘包括为什么这么设计、每一步怎么配、踩过哪些坑最后给出一份可以直接复现的配置模板。适合三类人看想把 AI 接入本地工作流的开发者、愿意折腾的自托管爱好者以及被各种玄学报错劝退的入门玩家。1. 项目整体设计与思路拆解1.1 OpenClaw 到底是什么OpenClaw 是一个开源的个人 AI 助手框架整体基于 Node.js/TypeScript 生态核心设计哲学是AI 不应该只停留在对话框里。它通过一套 skill技能机制把大模型的语义能力与真实系统的操作能力打通。你可以把 skill 理解成给 AI 安装的外挂工具包——执行终端命令、读写文件、调用浏览器、管理日程、处理办公文档这些都是以 skill 的形式挂载到助手身上的。这里有个关键认知得先摆正给 AI“完全系统权限”不是把所有权限一键开到最大而是让 AI 具备一套完整的、可被调度的系统操作能力。常见误区是觉得权限给得越宽越厉害实际项目中更合理的做法是分场景授权、按需挂载。我见过不少新手一上来就把宿主机根目录整个挂进容器结果 AI 在整理文件时把系统目录当普通目录处理虽然没出大事但也吓出一身冷汗。权限设计这件事下文我会专门用一节来拆。1.2 为什么选择 Docker Compose 而不是直接跑很多新手会问OpenClaw 不就是一个 Node.js 项目吗npm install 再 node 跑起来不就行了确实可以但站在长期使用和生产级稳定性角度我强烈推荐 Docker Compose理由有三个依赖隔离OpenClaw 对 Node 版本、原生依赖、Chromium 运行时等都有要求直接装宿主机上环境一乱就是玄学报错。容器把这层全部包住宿主机怎么折腾都不影响它。多服务编排一套完整的 OpenClaw 系统往往不止一个进程。接入本地模型需要 Ollama 服务做知识检索需要 embedding 模型服务常见的是 BGE-M3。用 Compose 可以把 OpenClaw、Ollama、Embedding 服务一次性拉起彼此通过容器网络互通不需要手动维护进程。配置即代码docker-compose.yml 能把环境变量、挂载目录、端口、重启策略全部固化。换机器迁移时一条命令恢复比手动配环境可靠太多。对比一下就知道差距直接跑的方式升级一次要手动处理依赖缓存、旧进程残留、端口冲突用 Compose 的话改一版配置、docker compose up -d滚动重建几分钟完事。1.3 开发者模式和常规模式的差异开发者模式developer mode是 OpenClaw 提供的一种实验性运行状态主要面向开发和调试场景。我一般只在做 skill 开发、权限策略调试、排查链路问题时开启日常使用并不会一直开着。它和常规模式的核心区别可以概括为三点开放更多调试接口和详细日志输出方便观察 AI 每一步的工具调用和决策过程相当于给助手装了透视镜。允许从本地路径加载未发布的 skill可以边写边测不用每次改完都重新发布。放宽部分默认安全限制所以绝不能直接用在公网生产环境。需要特别说明的是“开发者模式”是官方提供给开发者的调试通道不是用来绕过验证的开关。如果你在相关群里看到“开启开发者模式就能如何如何”的说法先保持警惕别为了省事牺牲安全。后面我会演示怎么在 Compose 配置里合法地开启它。2. 环境准备与基础依赖2.1 Windows 场景先把 WSL2 弄干净如果你用的是 WindowsDocker Desktop 默认依赖 WSL2 后端。这一步踩坑频率最高我那次部署就卡在这里。官方给过标准检查命令直接在 PowerShell 里执行wsl --status wsl --list --verbose我第一次执行wsl --status一直卡住换wsl -l -v才看到发行版列表里没有状态。这种时候不要急着重装 Docker先处理 WSL 本身管理员身份打开 PowerShell执行wsl --update更新完重启电脑再确认发行版状态是 Running。如果升级内核后还是异常去 BIOS 里确认虚拟化是否开启这一步经常被人忽略。2.2 安装 Docker 与 Docker Compose 插件Linux 服务器装 Docker EngineWindows 建议直接用 Docker Desktop装完先验证版本docker --version docker compose version注意一个细节现在官方推荐的是docker composeV2 插件而不是docker-composeV1 独立二进制后者已经停止维护了。如果你执行docker compose version报 command not found多半是 Docker 版本太老或者插件没启用。我在一台麒麟 V10 x86_64 机器上就遇到过系统源里的 Docker 版本陈旧的问题解决办法是卸载旧版本后按官方源在线安装新版 Docker 26然后给 Compose 插件单独配置执行权限这个路径在国产系统上尤其值得记录。2.3 准备本地模型服务Ollama 与 BGE-M3OpenClaw 本身不产生算力它需要一个推理后端。很多人问“OpenClaw 是不是只能用接入 API 的方式使用算力”答案是完全可以用本地模型。我当前的方案是 Ollama 提供主推理再挂一个 BGE-M3 做 embedding用于记忆和检索类 skill 的向量化。模型选择可以参考这张表场景推荐模型显存参考日常推理/助手对话qwen2.5:7b 或 llama3.1:8b8GB 左右更强推理/写代码qwen2.5:14b 或 codellama16GB 左右向量检索/embeddingbge-m3占用很小CPU 也能跑BGE-M3 可以单独起容器也可以在 Ollama 里直接ollama pull bge-m3我个人图省事统一走 Ollama少一个服务就少一个维护点。2.4 非 Windows 环境的部署差异Linux 和 macOS 的部署整体比 Windows 省心不需要前置处理 WSL2。macOS 装 Docker Desktop 后直接进入正题Linux 服务器则要额外注意用户组权限——把当前用户加入 docker 组否则每次执行 docker 命令都要 sudo。国内服务器如果拉镜像慢给 Docker 配一个镜像加速地址也是常规操作这属于基础环境优化不用多说。3. 核心配置与实操部署3.1 一份可直接抄的 docker-compose.yml下面这份配置是我当前在用的起步模板已经验证过可以跑通。注意具体镜像名和版本号会因为 OpenClaw 版本迭代而变动手前先去看一眼官方仓库的说明services: openclaw: image: openclaw/openclaw:latest container_name: openclaw-core restart: unless-stopped environment: OPENCLAW_MODE: developer OPENCLAW_MODEL_PROVIDER: ollama OPENCLAW_MODEL: qwen2.5:7b OPENCLAW_OLLAMA_BASE_URL: http://ollama:11434 OPENCLAW_EMBEDDING_PROVIDER: ollama OPENCLAW_EMBEDDING_MODEL: bge-m3 OPENCLAW_EMBEDDING_BASE_URL: http://ollama:11434 OPENCLAW_DATA_DIR: /data volumes: - ./data:/data - ./workspace:/workspace - ./skills:/skills ports: - 127.0.0.1:3000:3000 depends_on: - ollama ollama: image: ollama/ollama:latest container_name: openclaw-ollama restart: unless-stopped volumes: - ./ollama-models:/root/.ollama ports: - 127.0.0.1:11434:114343.2 环境变量逐项解读与参数选择我把配置里比较关键的变量拆开讲清楚理解了再改才不会瞎OPENCLAW_MODE: developer这是开启开发者模式的入口。我只在调试期间开跑稳定后会切回默认值。OPENCLAW_MODEL_PROVIDER: ollama推理后端走 Ollama模型名必须和 Ollama 里实际拉取的模型一致写错了容器能起来但 AI 一个请求都回不了。OPENCLAW_EMBEDDING_*向量模型配置我这里复用同一个 Ollama 服务省一个容器。端口绑定写成127.0.0.1:3000:3000只监听本机回环地址防止外部机器直接访问你的 AI 控制接口。这一步非常关键我见过有人图省事直接写3000:3000等于把控制口暴露到公网相当于把家门钥匙挂在门口。3.3 启动、验证与开发者模式确认在 docker-compose.yml 所在目录执行docker compose up -d docker compose logs -f openclaw第一次启动要拉镜像、初始化数据目录耐心等一两分钟。日志里看到类似 “OpenClaw is running in developer mode” 的输出说明已经进入开发者模式。然后访问http://127.0.0.1:3000打开控制面板先让它执行一个最简单的命令类 skill比如打印当前工作目录的文件列表验证从模型到执行器的完整链路通不通。我第一次验证这个动作时整个链路走了大几十秒一度以为卡死了其实只是本地模型首次加载慢后续就流畅了。3.4 Windows Companion 客户端配置OpenClaw 在 Windows 上还有一个 Companion 桌面端本质是独立的客户端进程通过本地网络连到核心服务。配置要点有三个核心服务只暴露在 127.0.0.1Companion 默认走 localhost 连接不需要额外开防火墙规则。Companion 的配置文件里填核心服务地址http://127.0.0.1:3000以及对应的访问 token。token 在核心服务日志或管理面板里生成填错的话界面会一直转圈。开发者模式下Companion 的调试面板会显示更详细的 skill 调用堆栈排查问题比默认模式直观得多。需要提醒的是Companion 和核心服务是两个概念别在“装了一个就算部署完”的理解上继续往下走。4. 权限体系与系统集成4.1 “完全系统权限”的工程实现标题里的“完全系统权限”落到工程上就是三件事文件系统访问、命令执行能力、外部服务调用。OpenClaw 在容器里默认有一个受限沙箱开发者模式配合挂载卷可以把它放宽到宿主机的指定目录。这是我整理的权限边界表权限类型默认容器状态开发者模式建议安全说明工作目录读写容器内隔离挂载 ./workspace建议只授权这一个目录自定义 skill 加载仅内置挂载 ./skills只加载你自己审阅过的 skill终端命令执行容器内受限用户保留容器内执行别轻易挂载 Docker socket网络访问出站默认放开限制回调地址防止 skill 向外部泄露数据我之前犯过一个典型错误图方便把宿主机根目录整个挂载进去AI 在整理文件时把/etc当普通目录处理虽然没出事故但日志里那些操作让我后怕。改成只挂载工作区目录后配合数据目录定期备份用起来才踏实。如果你确实需要让 AI 管理宿主机上的 Docker 容器比较稳妥的做法是暴露一个受控的 Docker socket 给专用容器而不是把docker.sock直接丢给主服务。这一步很进阶没有完全理解风险前不建议碰。4.2 Skill 机制先审权限再运行skill 就是 OpenClaw 的功能插件每个 skill 通常由一个 manifest 描述文件加若干执行脚本组成描述文件里声明这个技能需要哪些权限。开发者模式下加载自定义 skill 的目录结构大致是skills/ ├── my-skill/ │ ├── skill.json │ ├── main.js │ └── requirements.txt编写 skill 时我给自己定了两条铁律。第一manifest 里声明的权限最小化只声明它真正用到的而不是“反正开发者模式全开算了”。第二所有危险操作删除、覆盖、执行外部命令必须在输出里加入前置确认提示让 AI 在调用前明确告知用户。这样做不是保守是能保命的好习惯。我在写一个批量重命名文件的 skill 时因为没有加确认提示差点把一组带编号的资料全改成同名文件从那以后这条铁律再也没破过。4.3 本地算力还是 API 算力回到开头那个热门问题OpenClaw 完全可以用本地模型不是只有 API 一条路。具体怎么选我按场景给建议追求隐私和离线可用选 Ollama 本地模型数据不出机器断网也能跑适合处理敏感文档。追求复杂任务效果接云端 API推理质量更好但要注意 token 成本和数据出端的问题。混合方案日常任务走本地小模型复杂任务手动切 API。OpenClaw 支持按 skill 配置不同模型这是我觉得最实用的做法既省钱又不耽误质量。实测下来7B 级别的本地模型处理“整理文件、查资料、写脚本”这类任务完全够用真没必要一上来就堆大模型。5. 常见问题与排查实录5.1 WSL 环境异常导致 Docker 起不来症状很典型Windows 上执行 docker compose 报 WSL 相关错误或者 Docker Desktop 一直停在 Starting。先回到 2.1 节检查 WSL 状态然后执行wsl --shutdown再重开 Docker Desktop。如果升级内核后还是不行检查 BIOS 虚拟化开关。这个问题的本质是 Docker Desktop 的 Linux 后端没跑起来而不是 Compose 配置问题方向别搞错。5.2 Compose 启动即退出最经典的一个报错是 “cannot start docker compose application. reason: compose [start] exit status” 之类的看着吓人实际无非两个原因端口被占用、环境变量里的模型名写错。排查命令docker compose logs --tail200 openclaw docker ps -a日志里会直接给出原因是端口冲突还是某个依赖服务连不上照着改就行。另外注意depends_on只控制启动顺序不保证 Ollama 加载完模型首次启动后过几十秒再调用是正常节奏。5.3 模型连接失败或助手无响应确认 Ollama 容器内模型已拉取docker exec -it openclaw-ollama ollama list如果没有对应模型在宿主机执行docker exec -it openclaw-ollama ollama pull qwen2.5:7b。另外最容易被忽视的是 base URL 写法——Compose 网络内要用服务名http://ollama:11434而不是localhost因为容器里的 localhost 指向它自己。如果编辑器或外部工具提示“无法安全验证”一类的警告先检查你拉取的镜像是否来自官方仓库、digest 是否一致而不是强行关掉验证机制。5.4 排查速查表现象大概率原因处理办法容器起不来或退出端口冲突、环境变量错误看 logs改端口或变量AI 说没有权限操作文件挂载目录未授权检查 volumes把文件放进 workspaceCompanion 连不上核心服务token 未配置或绑定非 127.0.0.1重新生成 token检查端口绑定回答很慢本地模型偏小或没有 GPU换更大模型或走 APIskill 加载不出来目录结构或 manifest 声明错误对照 4.2 节检查文件路径和权限声明6. 两个安全忠告与后续扩展方向6.1 开发者模式的安全边界再强调一次开发者模式是为开发调试服务的不是拿去绕过验证的万能钥匙。把带开发者模式的 OpenClaw 暴露到公网等于把家门钥匙挂在门口。如果确实需要远程访问正确做法是在前面套一层带认证的反向代理同时坚持只读挂载、端口白名单这些常规约束。我见过一个项目把开发者模式的服务直接映射到公网第二天日志里全是扫描器的探测请求算是一个活生生的反面教材。6.2 后续玩法从“能干活”到“主动干活”我个人接下来的计划是给 OpenClaw 加一个定时任务 skill让它每天早上自动整理下载目录、汇总待办清单配合 BGE-M3 做本地知识库检索把“能动手”升级成“主动干活”。你也可以沿着这个方向扩展接 RSS 做信息过滤、挂日历做日程管理、把智能家居接口封装成 skill。手机端也有人用 Termux 跑轻量节点但手机算力有限更适合作为核心服务的远程客户端而不是主力计算节点。只要权限边界设计清楚这套东西的想象空间很大剩下的就靠你自己折腾了。