1. OpenClaw 容器化部署到底解决什么问题OpenClaw 是一个分布式爬虫框架能做什么简单说它把「抓取—解析—存储—调度」拆成可独立扩展的模块适合需要长期跑、数据量中等偏上的采集场景。适合谁适合已经在本地把脚本跑通、但一上服务器就遇到依赖冲突、Python 版本打架、进程莫名退出的开发者。我自己最早是把 OpenClaw 直接装在宿主机上结果换了一台机器lxml编译失败、cryptography版本对不上折腾了一下午。后来改成 Docker 容器化部署同样的镜像在哪台机器上跑行为都一致才算把「在我机器上好好的」这个魔咒破掉。但容器化只解决了一半问题。OpenClaw 要调用大模型做页面结构化抽取、正文清洗、字段补全时模型接入又成了新的坑每个爬虫节点都要配一份 Key换模型要改代码多节点并发时额度管理混乱。这篇实战指南的核心就是在 Docker 部署 OpenClaw 的全流程里用 TaoToken 统一 Key 和 API 通道把模型接入收敛到一处——镜像构建、环境变量注入、服务启动、容器内连通性验证每一步都给可复制的配置。读完之后你能拿到三样东西一份能直接用的docker-compose.yml、一套环境变量注入模型配置的写法、以及容器内验证 API 通道是否通的命令。全程不需要你懂 Docker 底层原理照着敲就行。先说清楚 TaoToken 在这里扮演的角色。它是一个统一的模型 API 网关官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。你只需要一个 Key就能在 OpenClaw 里切换不同模型不用为每个模型单独维护一套凭证。对容器化部署来说这点很关键——环境变量里只注入一个TAOTOKEN_API_KEY所有爬虫节点共享扩容时不用逐个改配置。下面按「环境检查 → 镜像构建 → compose 编排 → 模型接入 → 验证 → 排障」的顺序走每一步都有可复制的片段。2. 部署前环境检查与 TaoToken Key 准备动手之前先把宿主机环境确认一遍这一步能省掉后面一半的报错。OpenClaw 基于 Python容器化依赖 Docker 引擎和 Compose 插件所以先验证三件事Docker 版本、Compose 可用性、磁盘空间。检查 Dockerdocker --version # 期望输出类似Docker version 24.0.5, build ced0996如果命令不存在去 Docker 官网按操作系统下载稳定版Stable别用测试版生产环境求稳。接着验证 Compose。新版 Docker 已经把 compose 作为插件集成命令是docker compose无连字符旧教程里的docker-compose可能仍然可用但本文统一用官方推荐的写法docker compose version # 期望输出类似Docker Compose version v2.24.0磁盘空间方面爬虫会拉大量数据并写日志建议预留 10GB 以上df -h # 关注挂载点对应的 Avail 列确保 10G然后建一个专门的工作目录所有配置、源码、脚本都放这里结构清晰好备份mkdir -p openclaw-deploy cd openclaw-deploy环境确认完去拿 TaoToken 的 Key。打开 https://taotoken.net/api-keys 登录后创建一个 API Key复制出来先存到安全的地方。这个 Key 就是后面注入容器的唯一凭证。同时记下两个地址API 基址https://taotoken.net/api以及你打算用的模型 ID比如claude-sonnet-4-5这类具体以控制台模型列表为准。这里有个容易踩的坑很多人把 Key 直接写进docker-compose.yml然后提交到 Git等于把凭证公开了。正确做法是用.env文件存 Keycompose 通过变量引用.env加进.gitignore。下面第三节会给完整写法。如果你还没决定用哪个模型可以先到模型对话页面 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 试几个确认效果和响应速度再写进配置。长期跑编码类或 Agent 类任务的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 有更划算的额度方案可以按需看。3. 可复制的 Dockerfile 与 docker-compose 配置这一节是全文的核心给两份能直接落地的文件Dockerfile和docker-compose.yml重点演示环境变量怎么注入 TaoToken 配置。先写Dockerfile。OpenClaw 是 Python 应用基础镜像用 slim 版控制体积系统依赖在装 pip 包之前装好装完立刻清缓存FROM python:3.11-slim # 不生成 .pyc日志实时输出不缓冲 ENV PYTHONDONTWRITEBYTECODE1 ENV PYTHONUNBUFFERED1 # 编译型依赖需要的系统库 RUN apt-get update apt-get install -y --no-install-recommends \ gcc \ libxml2-dev \ libxslt1-dev \ zlib1g-dev \ curl \ rm -rf /var/lib/apt/lists/* WORKDIR /app # 先复制依赖清单利用镜像层缓存 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt # 再复制源码 COPY . . CMD [python, main.py]几个关键点PYTHONUNBUFFERED1保证docker compose logs能实时看到输出--no-install-recommends和清缓存能显著减小镜像先 COPY requirements 再 COPY 源码改代码时不会触发依赖重装。接着是docker-compose.yml。模型配置全部走环境变量Key 从.env读取version: 3.8 services: openclaw: build: . image: openclaw:latest container_name: openclaw-worker restart: unless-stopped env_file: - .env environment: - LOG_LEVELINFO - MAX_CONCURRENT5 - TAOTOKEN_BASE_URLhttps://taotoken.net/api - TAOTOKEN_MODELclaude-sonnet-4-5 volumes: - ./config:/app/config - ./data:/app/data - ./logs:/app/logs networks: - claw-net networks: claw-net: driver: bridge配套的.env文件记得加进.gitignoreTAOTOKEN_API_KEYsk-你的真实Key TAOTOKEN_BASE_URLhttps://taotoken.net/api TAOTOKEN_MODELclaude-sonnet-4-5注意environment里又写了一遍TAOTOKEN_BASE_URL和TAOTOKEN_MODEL这是故意的——env_file负责注入敏感 Keyenvironment负责显式声明非敏感配置两者叠加时environment优先级更高方便你在不改.env的情况下临时覆盖模型。三件套齐了Base URL、Key、Model ID缺一不可。OpenClaw 读取模型配置的地方通常在config/settings.yaml或代码里的环境变量读取逻辑。如果框架支持从环境变量读直接引用os.environ[TAOTOKEN_API_KEY]即可如果只认配置文件就在config/settings.yaml里写占位符启动脚本用envsubst替换。下面给一个settings.yaml的示例结构llm: provider: openai-compatible base_url: ${TAOTOKEN_BASE_URL} api_key: ${TAOTOKEN_API_KEY} model: ${TAOTOKEN_MODEL} timeout: 60 max_retries: 3 spider: timeout: 30 retries: 3 storage: path: /app/data format: json这样配置的好处是换模型只改.env一行重启容器生效不用重新构建镜像。多节点扩容时所有节点共享同一个 Key额度在 TaoToken 侧统一管理不会出现某个节点 Key 失效导致整批任务挂掉的情况。4. 构建镜像、启动服务与容器内连通性验证配置写完开始构建和启动。在openclaw-deploy目录下执行docker compose build构建过程会逐行执行 Dockerfile拉基础镜像、装系统库、装 pip 依赖、复制代码。如果拉基础镜像超时检查网络后重试即可。构建成功后确认镜像存在docker images | grep openclaw # 期望看到 openclaw latest xxxxx ... xxxMB然后后台启动docker compose up -d-d是 detached 模式终端不被日志占用。启动后先看状态docker compose ps # STATUS 列应为 Up如果显示Exit或Restarting别急第五节有排查清单。状态正常的话进入容器验证 Python 环境和依赖docker compose exec openclaw python --version # 期望Python 3.11.x最关键的一步验证容器内到 TaoToken API 通道是否通。用 curl 直接打 API 基址确认网络和 Key 都生效docker compose exec openclaw curl -s -o /dev/null -w %{http_code} \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ https://taotoken.net/api/models返回200说明通道通、Key 有效。如果返回401是 Key 问题返回000或超时是网络或 DNS 问题。这一步能在跑爬虫任务之前就把模型接入的问题暴露出来比等到任务执行到一半报错强得多。再验证一下环境变量确实注入进容器了docker compose exec openclaw env | grep TAOTOKEN # 应看到 TAOTOKEN_BASE_URL / TAOTOKEN_MODELKey 也会显示注意别截图外发环境变量、网络、Key 三样都验证通过就可以跑一个最小任务测试。假设 OpenClaw 的入口是main.py带一个测试 spiderdocker compose exec openclaw python main.py --spider example_spider观察./data目录下有没有新文件生成./logs下有没有正常日志。首次跑建议限制页数或深度快速验证链路通畅别一上来就全量抓。5. 常见报错排查401、local proxy failed、reading choices容器化部署 模型接入报错集中在几个固定位置。这一节按真实报错对照排查每个都给定位方法和修复动作。报错一401 Unauthorized。容器日志里出现401或invalid api key说明 Key 没注入成功或已失效。先确认容器内环境变量docker compose exec openclaw env | grep TAOTOKEN_API_KEY如果为空检查.env文件是否在 compose 同级目录、env_file路径是否正确、Key 有没有多余空格或引号。如果变量有值但仍 401去 https://taotoken.net/api-keys 确认 Key 是否被删除或额度耗尽必要时重新生成。注意.env里不要给值加引号TAOTOKEN_API_KEYsk-xxx这样写就行。报错二local proxy failed 或 connection refused。日志里出现local proxy failed、dial tcp ... connection refused通常是容器内 DNS 解析或出网问题。先在容器内测基础连通性docker compose exec openclaw curl -v https://taotoken.net/api/models如果卡在 DNS 解析给 compose 的 service 加 DNS 配置dns: - 8.8.8.8 - 1.1.1.1如果连 IP 都通但域名不通是 DNS 问题如果 IP 也不通检查宿主机防火墙是否放行 Docker 的出站流量。还有一种情况是公司内网有透明代理容器继承了宿主机的代理环境变量导致请求被劫持检查env | grep -i proxy把不需要的HTTP_PROXY/HTTPS_PROXY在 compose 里显式置空。报错三reading choices 或 index out of range。这类报错出现在模型返回解析阶段日志里常见reading choices、cannot read property of undefined。根因通常是 API 返回结构不符合预期——要么请求根本没成功返回了错误 JSON要么模型 ID 写错了导致返回体里没有choices字段。先确认TAOTOKEN_MODEL的值和控制台模型列表一致docker compose exec openclaw env | grep TAOTOKEN_MODEL再手动打一次请求看返回体docker compose exec openclaw curl -s \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d {model:$TAOTOKEN_MODEL,messages:[{role:user,content:hi}]} \ https://taotoken.net/api/chat/completions如果返回体里有error字段按错误信息处理如果有choices说明模型 ID 正确问题在 OpenClaw 的解析代码检查它读的是不是choices[0].message.content这个路径。报错四OAuth 相关错误。如果日志里出现OAuth、token expired、refresh failed说明你用的不是 API Key 模式而是 OAuth 模式。容器化场景下 OAuth 的 token 刷新很麻烦建议统一改用 API Key 方式接入把TAOTOKEN_API_KEY注入即可避免在容器里维护 OAuth 会话。报错五容器启动即退出。docker compose ps显示Exit 1先看日志docker compose logs --tail50 openclaw常见原因是requirements.txt里某个包在构建时没装全网络波动导致或者main.py启动时读配置失败。前者清理缓存重建docker builder prune -f docker compose build --no-cache后者检查./config挂载目录权限宿主机上执行chmod -R 755 ./config ./data ./logs确保容器内进程可读写。排查时记住一个原则先在容器内用 curl 验证 API 通道再验证环境变量最后看应用日志。把问题范围从「网络—凭证—代码」逐层缩小比盲目改配置快得多。6. 长期运行与统一 Key 接入的收尾建议服务跑起来只是开始长期稳定运行还得做几件事。数据持久化方面./data、./config、./logs三个目录已经挂载到宿主机容器删了数据还在。定期备份用一条命令就够tar -czvf openclaw_backup_$(date %F).tar.gz ./data ./config日志会随时间膨胀建议配 logrotate 或在应用侧限制单文件大小避免磁盘被写满。资源监控用docker stats openclaw-worker看 CPU 和内存如果内存持续上涨多半是爬虫任务里有未释放的对象需要回到代码层排查。统一 Key 接入的价值在扩容时才真正体现。当你从单节点扩到多节点只需要复制 compose 配置、改container_name所有节点共享.env里的同一个TAOTOKEN_API_KEY模型调用额度在 TaoToken 侧统一计量。换模型时改一行TAOTOKEN_MODELdocker compose restart全部节点生效不用逐个登录服务器改配置。这套模式我在几个采集项目里用过扩容和换模型的成本从「半天」压到「几分钟」。如果你还在选模型阶段可以到模型对话页面实际试几个再定确定要长期跑编码或 Agent 类任务Coding Plan 的额度方案比按量更省心。接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 里面有各语言 SDK 的调用示例容器里用 curl 或 Python requests 都能直接对接。最后留一个实用技巧把「容器内 curl 验证 API 通道」这一步写进你的部署脚本每次docker compose up -d之后自动跑一遍返回非 200 就告警。这样模型通道出问题能在任务启动前发现而不是等爬虫跑了一半才报错。部署这件事把验证前置比事后排查省心得多。