我一直觉得像 OpenClaw 这类带“技能系统”的 AI 代理工具最让人头疼的不是怎么把功能跑起来而是它口袋里的那串 API 密钥。命令行一启动配置文件一读取密钥就像家门钥匙压在门口地垫下面——方便是方便可谁路过都能翻一翻。后来我索性用 Docker 把 OpenClaw 整个关进沙盒环境隔离、密钥注入、文件权限全部重做了一遍实测下来确实踏实多了。这篇文章就聊聊我怎么做的以及容器化之后遇到的那些坑。如果你也在用 OpenClaw或者准备部署一个需要调用大模型 API 的自动化代理这篇文章的整套思路可以直接照搬。无论你是跑在 Windows 的 Docker Desktop 上还是 Ubuntu 服务器上用 Docker Engine重点只有一个让密钥不在镜像里、不在代码里、不在日志里只在运行时的环境变量里存在。1. 为什么我非要把 OpenClaw 塞进 Docker密钥裸奔那点事1.1 裸奔的密钥是怎么“漏”出去的先说一个我自己的真实翻车现场。最早我把 OpenClaw 直接装在本地 Linux 机器上配置文件config.yaml里理所当然写着api_key: sk-xxxx。当时想着反正是单机不联网就行结果有次调试某个技能OpenClaw 的日志模块把整个配置对象打印了出来包括完整密钥。日志文件刚好我又同步到了网盘里等于钥匙复制了好几把放在公共储物柜里。这还不是最离谱的。如果你装了第三方技能包技能代码运行在和你 OpenClaw 同样的用户权限下它完全可以读配置文件、读环境变量把密钥悄悄传出去。OpenClaw 的技能机制很灵活但越灵活越要防一手。API 密钥这东西一旦泄露就是真金白银的消耗按 token 计费的模型跑个一晚上账单能让你怀疑人生。另一个常见坑是 Git 仓库。很多人喜欢把配置目录直接纳入版本管理一个git push到公开仓库密钥就永远躺在提交历史里了。就算你马上删掉历史里依然能翻出来。所以密钥必须和代码、配置文件彻底分离。1.2 沙盒隔离到底隔离了什么Docker 在这里解决的不是“性能”问题而是“边界”问题。它给 OpenClaw 划了一个独立的小房间房间里的文件系统和宿主机是隔开的进程也看不到外面的进程。更关键的是镜像构建完是只读的运行时你通过环境变量把密钥“注射”进去密钥不会写进磁盘也不会进入镜像层。我自己理解的沙盒有三层文件隔离容器里默认看不到宿主机上的~/.ssh、/home/用户这些敏感目录除非你手动挂载。进程隔离容器内的 OpenClaw 即使被恶意技能攻击它也拿不到宿主机的 root 权限更碰不到其他容器。网络隔离可以用--network指定容器网络控制它能访问哪些服务外部想访问 OpenClaw 也得经过端口映射。有了这三层API 密钥就不再是“躺在文件里的明文”而是“运行内存里的临时值”。这就是我后来坚持容器化的根本原因。2. 环境准备从 Docker Desktop 到 Linux 引擎的安装与避坑2.1 Docker Desktop 还是 Docker Engine按平台选我日常开发主力机是 Windows服务器是 Ubuntu。两边的选型不一样。Windows 上推荐直接用 Docker Desktop它自带图形界面、文件共享、WSL2 集成对新手最友好。下载安装包装完重启基本就能用。不过它依赖 Windows 的虚拟化功能如果你的机器太老或者虚拟机平台没开大概率会启动失败。Linux 服务器上就没必要装 Docker Desktop 了直接用 Docker Engine 更轻量。Ubuntu 下的安装命令很简单sudo apt update sudo apt install -y ca-certificates curl gnupg sudo install -m 0755 -d /etc/apt/keyrings curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg sudo chmod ar /etc/apt/keyrings/docker.gpg echo \ deb [arch$(dpkg --print-architecture) signed-by/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \ $(. /etc/os-release echo $VERSION_CODENAME) stable | \ sudo tee /etc/apt/sources.list.d/docker.list /dev/null sudo apt update sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin装完验证一下docker version能看到 client 和 server 版本就说明守护进程正常。如果你的系统是 CentOS 或者 Fedora命令稍有不同但思路一样装docker-ce和docker-compose-plugin。别再用老的docker-compose独立二进制了新项目直接docker compose子命令更顺手。2.2 启动 Docker 时最常见的两个拦路虎装完 Docker 后最容易遇到两个错误我帮朋友排查N次了。第一个是 Windows 上 Docker Desktop 弹窗Docker Desktop failed to start because virtualization support wasnt detected。这基本是 BIOS 里的虚拟化没开。重启进 BIOS找Intel Virtualization Technology (VT-x)或者AMD SVM选项启用它。注意有的主板默认是禁用装好了 Docker 才发现这事确实很折腾。另外如果开了 WSL2还要保证 Windows 的“虚拟机平台”功能是启用状态可以在管理员 PowerShell 里跑dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart。第二个是 Linux 下报permission denied while trying to connect to the Docker daemon socket。原因是当前用户不在docker用户组里。解决办法sudo usermod -aG docker $USER newgrp docker然后重新登录终端再docker ps试试。注意如果之前用的是sudo docker之后尽量别混用组权限和 sudo 权限管理思路不同混用容易搞乱目录权限。还有一个镜像拉取慢的问题。如果你在国内网络环境直接从 Docker Hub 拉镜像确实会慢得让人抓狂。我的做法是配置一个可信的镜像加速地址在/etc/docker/daemon.json里写好 registry-mirrors然后重启 docker 服务。不同加速源稳定性有差异建议至少配置两个。3. 构建 OpenClaw 容器官方镜像、Dockerfile、Compose 三选一3.1 官方镜像直跑快速验证如果你只是想在几分钟内把 OpenClaw 跑起来看看效果直接用官方镜像最快。假设项目官方维护了镜像我用的是 openclaw/openclaw 这个 tag 示例具体以你所在仓库为准docker run -d \ --name openclaw \ -p 8080:8080 \ -e OPENAI_API_KEYsk-xxxx \ -v openclaw-data:/var/lib/openclaw \ openclaw/openclaw:latest这个命令干了几件事-d后台运行-p 8080:8080把容器的 Web 端口映射到宿主机-e OPENAI_API_KEY注入密钥-v openclaw-data创建命名卷把持久化数据存到卷里以后删容器也不丢数据。跑起来之后浏览器打开http://localhost:8080能看到 OpenClaw 的控制台就说明基础环境通了。但官方镜像不一定随时覆盖你的需求。比如你想加自己的技能包或者内置某个 Python 依赖官方镜像里可能没有。这时候就得自己写 Dockerfile或者用 Compose 挂载技能目录。3.2 自定义镜像把技能和依赖打包进去我第二次部署就用了自定义镜像因为我在 OpenClaw 里加了几个自定义技能需要用到requests、beautifulsoup4这类库。官方镜像的虚拟环境里没有所以我直接基于 Python 官方镜像来构建。FROM python:3.11-slim WORKDIR /app # 安装 OpenClaw 及其依赖 RUN pip install --no-cache-dir openclaw # 拷贝技能目录和示例配置 COPY skills/ ./skills/ COPY config.example.yaml ./config.yaml # 以非 root 用户运行降低特权风险 RUN useradd -m -u 1000 openclaw \ chown -R openclaw:openclaw /app USER openclaw EXPOSE 8080 CMD [openclaw, serve]这里有两个细节很关键。第一COPY config.example.yaml ./config.yaml拷进去的是一个不含密钥的模板文件密钥必须靠运行时环境变量注入。防止有人直接docker cp拿走你的镜像在镜像层里翻出密钥。第二用非 root 用户运行。容器里默认是 root一旦 OpenClaw 被远程命令注入攻击攻击者可能是 root 身份。虽然容器内 root 和宿主机 root 不完全等价但权限还是越小越好。我这里创建了 uid1000 的用户和宿主机普通用户对等。构建命令docker build -t openclaw-custom:latest .之后运行和官方镜像类似只是镜像是你自己打出来的。3.3 Compose 编排OpenClaw Ollama 日志服务当你开始加周边组件时单条docker run就不够了。我现在用 Docker Compose 管理 OpenClaw 和本地大模型服务一个compose.yaml文件搞定services: openclaw: build: . image: openclaw-custom:latest env_file: - .env ports: - 8080:8080 volumes: - ./data:/app/data - ./skills:/app/skills depends_on: - ollama restart: unless-stopped ollama: image: ollama/ollama:latest ports: - 11434:11434 volumes: - ollama-models:/root/.ollama restart: unless-stopped volumes: ollama-models:env_file会自动读取当前目录下的.env文件把里面的键值对注入容器的环境变量。这样 compose 文件里不出现任何明文密钥.env单独维护并且加入.gitignore。depends_on只是控制启动顺序不保证 ollama 服务已经准备好了。如果 OpenClaw 启动太快连不上 ollama可以配合 healthcheck 或者让 OpenClaw 支持重试。我在实际使用中习惯在 OpenClaw 的配置里把 ollama 的 base_url 设为http://ollama:11434容器间通过服务名直连不用操心 IP 变化。4. 密钥安全让 API Key 不进镜像、不进代码、不进日志4.1 环境变量注入的正确姿势很多人第一次用 Docker 时喜欢在 Dockerfile 里写ENV OPENAI_API_KEYsk-xxxx这是大忌。镜像是由一层层文件组成的ENV指令会把密钥明文写进镜像层别人拉取或导出镜像后用docker history就能看到。正确的姿势是运行时注入docker run -e OPENAI_API_KEY$(cat ~/.openai_key) ...或者写进.env再通过env_file让 Compose 读取。可能有人问构建的时候怎么办有些 Python 包安装时需要 API Key 作为凭据这时候要用 BuildKit 的--secret特性而不是ARG。因为ARG也会被docker history记录。使用方式docker build --secret idapikey,src./.env .Dockerfile 里RUN --mounttypesecret,idapikey eval $(cat /run/secrets/apikey)这样密钥只存在于构建时的临时挂载文件里不会留进镜像层。实测这个功能非常实用尤其是个别代理需要调用私有源拉依赖包时。4.2 .env 文件与 Docker Secrets 怎么选我现在的习惯是分环境开发环境用.env文件。简单直接Compose 自动读取改完重启容器就生效。生产环境用 Docker Secrets或者干脆用服务器上的密钥管理服务。.env文件注意三点文件权限设为600chmod 600 .env加入.gitignoreecho .env .gitignore文件名建议用.env而不是.env.local因为 Compose 默认只读取.envDocker Secrets 的用法也不复杂适合单个密钥printf sk-xxxx | docker secret create openai_key -然后在 compose 文件里声明services: openclaw: image: openclaw-custom:latest secrets: - openai_key secrets: openai_key: external: true容器内密钥会被挂载到/run/secrets/openai_key文件你的应用需要主动读取这个文件。OpenClaw 如果不原生支持读取 secret 文件你可能要写一个小包装入口把文件内容读到环境变量后再启动。4.3 挂载目录的权限设计容器里的数据卷最怕权限乱。我之前用 root 用户跑容器结果在宿主机上留下的数据文件全部属于 root普通用户想删都删不掉。后来统一用命名卷 非 root 用户问题干净解决。如果你挂载了一个宿主机目录到容器里比如./data:/app/data建议在容器启动时指定用户 UIDdocker run -u $(id -u):$(id -g) -v ./data:/app/data ...Compose 里也可以在服务下写user: 1000:1000。还有一个容易忽略的地方不要把宿主机的~/.ssh、/etc/passwd、/var/run/docker.sock随便挂载进容器。有些人为了让 OpenClaw 能操作宿主机 Docker直接挂载/var/run/docker.sock这等于给了容器宿主机 root 权限极其危险。如果一定要联动宿主机服务优先考虑用 API 或网络接口而不是给 socket 权限。5. 沙盒内 OpenClaw 的日常指挥启动、升级、排障5.1 容器生命周期管理命令容器跑起来之后日常用到的命令其实就那几个。我把自己的高频命令列一下# 查看容器状态 docker ps -a | grep openclaw # 看日志最常用 docker logs -f openclaw # 进入容器调试 docker exec -it openclaw bash # 重启容器 docker restart openclaw # 停用并删除 docker rm -f openclaw需要注意docker logs -f会显示容器内 stdout 和 stderr。如果你发现日志里有打印完整环境变量或密钥内容的情况一定要在 OpenClaw 的日志级别里关掉配置打印。比如把 log 等级调到warning或者用过滤器脱敏。我早期就被这条坑过后来加了日志脱敏插件才算放心。进入容器后可以手动执行 OpenClaw 的 CLI 命令。比如查看技能列表docker exec -it openclaw openclaw skill list更新某个技能docker exec -it openclaw openclaw skill update skill-name这些操作不会影响宿主机环境改坏了直接docker rm -f重新跑一个根本不用怕。5.2 如何验证你的 API 密钥真的“没裸奔”部署完不能光看能跑就说安全我一般做三遍检查。第一遍检查镜像历史docker history --no-trunc openclaw-custom:latest | grep -i api_key\|sk- || echo 镜像层中没有发现密钥如果输出为空说明构建层没泄。第二遍检查环境变量是否被写入配置文件。进入容器docker exec openclaw cat /app/config.yaml | grep api_key我期望看到的是类似${OPENAI_API_KEY}的引用而不是明文。第三遍把.env文件临时移到别处重启容器mv .env /tmp/env.bak docker restart openclaw如果 OpenClaw 还能正常调用 API说明密钥已经通过环境变量注入且没有回写文件如果它启动报“缺少 API Key”你得检查是不是某个启动脚本把环境变量重新写进了配置。我自己的经验是OpenClaw 的配置解析如果支持${ENV_VAR}语法那就不用担心回写问题如果不支持你只能在入口脚本里做一个“从环境变量生成配置文件但不落盘”的临时方案比如用/dev/shm。5.3 数据持久化和镜像更新容器最大的好处之一是升级方便。以前宿主机装新版 OpenClaw我得先备份旧环境再卸载重装中间出了错还回不去。现在只需要改镜像 tag然后docker compose pull openclaw docker compose up -d数据卷里的技能、配置、任务历史都在容器替换不影响数据。但注意如果新版镜像改了数据目录结构或者配置文件格式不兼容直接升级可能报错。我的建议是升级前先备份数据卷docker run --rm -v openclaw-data:/data -v $(pwd):/backup alpine tar czf /backup/openclaw-backup.tar.gz -C /data .把备份文件下载到本地再升级。如果出问题回滚也就是重新指定老镜像版本。6. 容器化后的实测体验和几个坑6.1 网络模式我为什么最后选了 bridge一开始我图省事直接用了--network host。在 Linux 上host 模式让容器直接共享宿主机网络端口不用映射访问localhost:8080就能进 OpenClaw。但问题随之而来host 模式下容器和宿主机之间的网络隔离基本失效OpenClaw 一旦被攻破它对本机其他服务的访问范围和宿主机进程一样大。这和“沙盒”初衷是矛盾的。最后我换回默认 bridge 模式用-p显式映射端口。容器内部通过http://172.17.0.1访问宿主机上的服务通过http://ollama:11434访问 compose 里的其他容器。隔离更彻底也没损失多少性能。如果你在 Docker Desktop 上需要访问宿主机服务直接用host.docker.internal域名。Linux 上要手动加一个docker run --add-host host.docker.internal:host-gateway ...Compose 里对应extra_hosts: - host.docker.internal:host-gateway6.2 资源限制N100 小主机也能跑我后来专门弄了一台 N100 小主机软路由兼跑 Docker。原本担心容器化 OpenClaw 太吃资源实测下来还好。OpenClaw 本身是一个 Python 应用空载内存大约 200-400MB加上本地 Ollama 跑小模型俩容器总共吃 2GB 左右。为了不让它把整台机器拖垮我给 OpenClaw 做了资源限制services: openclaw: deploy: resources: limits: cpus: 1.0 memory: 1g这样即使某个技能陷入循环也不会把 N100 的四个核心全部吃满。实际上在top里观察OpenClaw 的 CPU 占用平时不到 5%只有处理复杂任务时会短暂升到 50% 以上。容器化没带来明显的性能损失但换来了“出了事不牵连宿主机”的安心。6.3 和本地 Ollama 通信的曲折经历最后说说和 Ollama 通信的坑。我在 compose 里同时跑了 OpenClaw 和 OllamaOpenClaw 的配置里把模型地址指向http://ollama:11434。结果第一次调用一直超时原因有两个。第一个是启动顺序。Ollama 容器虽然先启动了但模型加载需要时间OpenClaw 连接时模型还没就绪。解决办法是给 Ollama 加 healthcheckhealthcheck: test: [CMD, curl, -f, http://localhost:11434/api/tags] interval: 10s retries: 5然后 OpenClaw 的depends_on加上condition: service_healthy。第二个是容器内网络请求外网 API 时如果模型调用走代理OpenClaw 的 HTTP 客户端默认不读容器内环境变量的代理配置得在 OpenClaw 的配置文件里显式设置http_proxy和https_proxy。不过为了密钥安全API 请求建议走 HTTPS避免中间人窃听。容器的网络出口我默认放行 443 端口其余端口按需开。还有一个冷知识如果你把 OpenClaw 容器和 MongoDB 容器放在同一个 compose 网络中网络名称默认是项目名_默认。在 OpenClaw 容器内可以通过服务名访问 MongoDB但如果你从宿主机直接访问容器 IP可能会因为网络隔离而失败。刚开始排查问题时要分清楚是容器间通信还是宿主机到容器通信别混在一起猜。最后聊两句我的真实感受做了这轮容器化改造之后我最大的收获不是“跑得更快”而是心态变了。以前改配置、加技能、升级版本总怕把宿主机搞乱现在随便折腾删了重来。API 密钥也规矩地待在.env里开机自动注入关机不留痕迹。如果你想在安卓手机上用 Termux 部署 OpenClaw其实一样可以用 Docker 的思路只不过 Termux 里的 Docker 兼容性相对折腾我更推荐在局域网里放一台小主机专门跑容器。如果你还没迁移我给你的建议很简单从 Compose 开始哪怕只有一个服务也先把.env和docker-compose.yml分好层。等哪天真出了安全事故你会发现这一步省下的不只是一张账单。