OpenClaw Linux 部署手册：常规安装、Docker 与 Docker Compose 接入 TaoToken 配置指南

1. 为什么要在 Linux 上折腾 OpenClaw 的三种部署方式OpenClaw 是一个 AI Agent Gateway简单说就是把你常用的聊天渠道、CLI 工具、Control UI 统一接到一个常驻服务上再由它去调用背后的模型。它支持 CLI、常驻 Gateway、Control UI 和多渠道接入Linux 是官方推荐的生产部署平台。很多人第一次接触会卡在同一个地方装是装上了但模型通道没接对Gateway 起来了却调不通模型。这篇就聚焦 OpenClaw 在 Linux 上的三条部署路径——常规安装、Docker、Docker Compose重点演示怎么通过统一 Key/API 通道 TaoToken 完成模型接入。我会给出可复制的 config.toml 与 settings.json 骨架、Docker Compose 环境变量片段以及容器内连通性验证和日志排查动作。适合已经有一台 Linux 机器、想跑一个稳定 Agent Gateway 的开发者也适合在 VPS 上做隔离部署的运维同学。三种方式各有取舍常规安装上手最快Docker 适合不想污染宿主机环境Docker Compose 是官方推荐的生产方式。下面按顺序来每一步都给验收命令。2. 接入前的准备TaoToken 统一 Key 与 API 通道在动 OpenClaw 之前先把模型通道准备好。TaoToken 提供统一的 Key/API 通道你只需要一个 API Key 和一个 Base URL就能在 OpenClaw 里配置模型调用不用为每个模型单独维护一套凭证。你需要拿到两样东西API Key 和 API 地址。API 地址是https://taotoken.net/apiKey 在控制台创建。创建入口在这里控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsoleAPI Keys 管理https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys注意API 地址不要带 UTM 参数直接写https://taotoken.net/api即可带参数的地址是给页面跳转用的接口调用会失败。拿到 Key 之后先别急着配 OpenClaw用 curl 验证一下通道本身是通的curl -fsS https://taotoken.net/api/v1/models \ -H Authorization: Bearer $TAOTOKEN_API_KEY如果返回模型列表说明 Key 和通道都没问题。这一步很关键因为后面 OpenClaw 报错时你要能区分是通道问题还是 OpenClaw 配置问题。我试过先跳过这步结果在容器里排查了半天最后发现是 Key 复制时多了个空格。3. 方式一常规安装并接入 TaoToken常规安装适合个人本机或开发机依赖 Node.js 24推荐或 22.19内存至少 1 GB。默认端口 Gateway 是 18789Bridge 是 18790。3.1 一键安装脚本curl -fsSL https://openclaw.ai/install.sh | bash如果你想跳过交互式 onboarding直接加参数curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard如果不想依赖系统 Node可以用本地 prefix 安装OpenClaw 和 Node 都会装到~/.openclaw前缀下curl -fsSL https://openclaw.ai/install-cli.sh | bashnpm 全局安装也可以npm install -g openclawlatest openclaw onboard --install-daemon3.2 配置守护进程openclaw onboard --install-daemon在 Linux/WSL2 上这会创建 systemd user service实现 Gateway 开机自启。装完之后验证一下openclaw --version openclaw doctor openclaw gateway status curl -fsS http://127.0.0.1:18789/healthz浏览器打开http://127.0.0.1:18789/在 Settings 里粘贴 Gateway Token 就能进 Control UI。3.3 config.toml 接入 TaoToken 骨架OpenClaw 的模型通道配置放在配置目录下。常规安装的配置目录通常是~/.openclaw。下面是一个可复制的config.toml骨架把模型指向 TaoToken[gateway] mode local bind lan port 18789 [gateway.controlUi] allowedOrigins [http://localhost:18789, http://127.0.0.1:18789] [models] provider openai-compatible baseUrl https://taotoken.net/api apiKey ${TAOTOKEN_API_KEY} defaultModel gpt-4o-mini [models.params] timeout 60 maxRetries 2这里provider用openai-compatible因为 TaoToken 的接口是 OpenAI 兼容格式。apiKey用环境变量引用避免把 Key 写死在文件里。defaultModel换成你在控制台确认可用的模型名。3.4 settings.json 骨架有些版本或渠道配置会读settings.json骨架如下{ gateway: { mode: local, bind: lan, port: 18789 }, models: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, defaultModel: gpt-4o-mini }, channels: { telegram: { enabled: false } } }把TAOTOKEN_API_KEY写进你的 shell 环境或 systemd service 的 Environment 里export TAOTOKEN_API_KEY你的Key如果是 systemd user service编辑~/.config/systemd/user/openclaw-gateway.service在[Service]段加一行EnvironmentTAOTOKEN_API_KEY你的Key然后systemctl --user daemon-reload systemctl --user restart openclaw-gateway。3.5 验证模型调用配置改完后重启 Gateway然后发一个测试请求curl -fsS http://127.0.0.1:18789/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer $OPENCLAW_GATEWAY_TOKEN \ -d { model: gpt-4o-mini, messages: [{role: user, content: ping}] }返回里有choices字段就说明 OpenClaw 已经通过 TaoToken 调通了模型。如果返回 401先检查 Gateway Token如果返回模型不存在检查defaultModel是否和控制台一致。4. 方式二Docker 部署并接入 TaoTokenDocker 部署适合不想污染宿主机环境或者在 VPS 上做隔离运行的场景。前置条件是 Docker Engine Compose v2本地构建镜像建议内存 ≥ 2 GB。4.1 确认环境docker --version docker compose version4.2 使用官方 setup 脚本git clone https://github.com/openclaw/openclaw.git cd openclaw ./scripts/docker/setup.sh小内存 VPS 推荐直接用预构建镜像避免构建时 OOMexport OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh脚本会自动构建或拉取镜像、交互式 onboarding、生成.env和 Gateway Token并通过 Docker Compose 启动 Gateway。4.3 手动 Docker 流程如果你想自己控制每一步docker build -t openclaw:local -f Dockerfile . docker compose run --rm --no-deps --entrypoint node openclaw-gateway \ dist/index.js onboard --mode local --no-install-daemon docker compose run --rm --no-deps --entrypoint node openclaw-gateway \ dist/index.js config set --batch-json [{path:gateway.mode,value:local},{path:gateway.bind,value:lan},{path:gateway.controlUi.allowedOrigins,value:[http://localhost:18789,http://127.0.0.1:18789]}] docker compose up -d openclaw-gateway4.4 容器内注入 TaoToken 环境变量Docker 部署时模型 Key 通过环境变量注入。编辑.env文件加上TAOTOKEN_API_KEY你的Key OPENCLAW_GATEWAY_TOKEN你的GatewayToken OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest然后在docker-compose.yml的openclaw-gateway服务里引用services: openclaw-gateway: image: ${OPENCLAW_IMAGE:-openclaw:local} environment: HOME: /home/node OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN} TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace ports: - ${OPENCLAW_GATEWAY_PORT:-18789}:18789 - ${OPENCLAW_BRIDGE_PORT:-18790}:18790 restart: unless-stopped command: [node, dist/index.js, gateway, --bind, lan, --port, 18789]4.5 容器内连通性验证容器起来后先进容器确认环境变量和网络都正常docker compose exec openclaw-gateway sh -c echo $TAOTOKEN_API_KEY | head -c 8 docker compose exec openclaw-gateway sh -c curl -fsS https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY第一条确认 Key 注入成功只打印前 8 位避免泄露第二条确认容器内能访问 TaoToken。如果第二条失败先检查容器 DNS 和出网策略。健康检查curl -fsS http://127.0.0.1:18789/healthz curl -fsS http://127.0.0.1:18789/readyz4.6 日志排查docker compose logs -f openclaw-gateway重点看有没有ECONNREFUSED、401、model not found这类关键字。ECONNREFUSED通常是容器网络问题401是 Key 问题model not found是模型名写错。5. 方式三Docker Compose 生产部署与 TaoToken 配置Docker Compose 是官方推荐的生产方式。官方docker-compose.yml包含两个服务openclaw-gateway常驻 Gateway对外暴露 18789/18790openclaw-cli是一次性 CLI 容器用来执行管理命令。5.1 标准 Compose 结构services: openclaw-gateway: image: ${OPENCLAW_IMAGE:-openclaw:local} environment: HOME: /home/node OPENCLAW_GATEWAY_TOKEN: ${OPENCLAW_GATEWAY_TOKEN} TAOTOKEN_API_KEY: ${TAOTOKEN_API_KEY} volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace ports: - ${OPENCLAW_GATEWAY_PORT:-18789}:18789 - ${OPENCLAW_BRIDGE_PORT:-18790}:18790 restart: unless-stopped command: [node, dist/index.js, gateway, --bind, lan, --port, 18789] openclaw-cli: image: ${OPENCLAW_IMAGE:-openclaw:local} network_mode: service:openclaw-gateway volumes: - ${OPENCLAW_CONFIG_DIR:-~/.openclaw}:/home/node/.openclaw - ${OPENCLAW_WORKSPACE_DIR:-~/.openclaw/workspace}:/home/node/.openclaw/workspace entrypoint: [node, dist/index.js]完整文件以官方仓库docker-compose.yml为准。5.2 一键启动cd openclaw export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh5.3 常用 Compose 命令docker compose up -d openclaw-gateway docker compose logs -f openclaw-gateway docker compose down docker compose run --rm openclaw-cli channels add --channel telegram --token token docker compose run --rm openclaw-cli channels login docker compose run --rm openclaw-cli devices list docker compose run --rm openclaw-cli devices approve requestId5.4 环境变量对照变量用途OPENCLAW_IMAGE使用远程预构建镜像OPENCLAW_GATEWAY_TOKENGateway 认证 TokenOPENCLAW_CONFIG_DIR配置目录挂载路径OPENCLAW_WORKSPACE_DIR工作区挂载路径OPENCLAW_SANDBOX启用 Agent Sandbox1/trueOPENCLAW_SKIP_ONBOARDING跳过交互式 onboardingTAOTOKEN_API_KEYTaoToken 统一 Key注入模型通道5.5 持久化目录与权限容器 bind-mount 以下路径替换容器后数据保留~/.openclaw存配置、openclaw.json、.env~/.openclaw/workspace是 Agent 工作区。容器以 uid 1000node运行宿主机挂载目录需要改权限sudo chown -R 1000:1000 ~/.openclaw这一步不做容器会报权限拒绝日志里能看到EACCES。5.6 启用 Agent Sandboxexport OPENCLAW_SANDBOX1 ./scripts/docker/setup.shSandbox 在独立 Docker 容器中执行 Agent 工具Gateway 仍在主容器中运行。生产环境建议开启隔离工具执行。5.7 Compose 下的模型验证docker compose exec openclaw-gateway sh -c curl -fsS http://127.0.0.1:18789/healthz docker compose exec openclaw-gateway sh -c curl -fsS https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY两条都通过再发一次 chat completions 请求确认端到端通了。6. 三种方式对比与选型建议维度常规安装DockerDocker Compose上手速度最快中等中等环境隔离低高高适合场景个人本机/dev单容器验证VPS/生产依赖Node.jsDocker EngineDocker Compose v2升级openclaw update拉取新镜像compose pull up如果你只是本机试玩常规安装最省事。如果要在 VPS 上长期跑直接上 Docker Compose配合 TaoToken 的环境变量注入升级和迁移都干净。Docker 单容器适合快速验证镜像能不能跑起来。7. 本篇常见错误排查7.1 构建镜像 OOMexit 1371 GB 内存 VPS 构建会失败。改用预构建镜像export OPENCLAW_IMAGEghcr.io/openclaw/openclaw:latest ./scripts/docker/setup.sh7.2 容器内访问 TaoToken 失败先在容器里测docker compose exec openclaw-gateway sh -c curl -v https://taotoken.net/api/v1/models -H Authorization: Bearer $TAOTOKEN_API_KEY如果卡在 DNS检查/etc/resolv.conf如果返回 401检查 Key 是否有多余空格或换行。7.3 模型名不匹配defaultModel必须和控制台里可用的模型名一致。写错会返回model not found。建议先用/v1/models列出可用模型再填进配置。7.4 权限拒绝 EACCES宿主机挂载目录属主不对sudo chown -R 1000:1000 ~/.openclaw7.5 Gateway Token 不匹配Control UI 进不去或 API 返回 401检查.env里的OPENCLAW_GATEWAY_TOKEN和你在 Settings 里粘贴的是否一致。改完 Token 要重启容器。7.6 端口被占用18789 或 18790 被占用时改.env里的OPENCLAW_GATEWAY_PORT和OPENCLAW_BRIDGE_PORT然后docker compose up -d重建。8. 下一步把通道和部署都固定下来部署跑通之后建议把 TaoToken 的 Key 和 OpenClaw 的 Gateway Token 都放进.env或 systemd 的 Environment不要写死在配置文件里。这样换机器、升级镜像时只需要替换环境变量。如果你还在选模型阶段可以先用模型对话页面确认哪些模型可用再填进defaultModel模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchat如果你打算长期跑编码类 Agent或者需要更稳定的调用配额可以看 Coding PlanCoding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan接入文档里有完整的配置字段说明遇到本文没覆盖的字段可以去查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后提醒一句容器内验证连通性时先测https://taotoken.net/api/v1/models再测 OpenClaw 的/healthz两个都通过再发 chat 请求。这样出问题时能快速定位是通道层还是 Gateway 层比一上来就发对话请求省时间。