用 Docker 跑龙虾和直接装有什么区别？

最大区别是干净。Docker 把 Node 运行时和龙虾的全局包全封在容器里，不碰你本机的环境，删容器就等于卸干净，不留垃圾。代价是镜像要占几个 G 的硬盘，第一次拉镜像也慢一点。如果你机器上已经有别的 Node 项目、怕版本打架，或者想要一个随时可以整个扔掉重来的隔离环境，用 Docker 最省心。

容器一关，配置和数据会丢吗？

看你有没有挂载。如果用 volumes 把配置目录、数据目录挂到了本机，那容器删了重建也不丢，数据都在本机那个目录里。没挂载的话，容器内写的东西会跟着容器一起没。所以 .env 和数据目录一定要挂出来。

容器里能调用本机的浏览器或文件吗？

文件可以——把本机目录挂进容器，龙虾就能读写那个目录。本机的图形界面浏览器默认进不去容器，所以浏览器自动化通常用容器内自带的无头浏览器。需要让它操作本机桌面级软件的场景，Docker 反而不方便，那种情况建议直接本地装。

教程 · 部署

用 Docker 部署 OpenClaw 龙虾：一条命令起跑

钳叔 · 龙虾AI 编辑部 · 2026-08-23 · 约 11 分钟

本机装龙虾要先备好 Node，再往全局装一个包，机器上已经有别的 Node 项目的话，稍不留神就版本打架。Docker 把这些麻烦全装进一个盒子里——用官方脚本拉一个现成镜像，起一条命令，龙虾就跑起来了，而且不碰你本机的环境，不想要了整个扔掉。官方自己也把 Docker 定位成“可选项”：要隔离、要一次性环境、或者机器上不想装 Node 时才用它；本机能直接装的，走普通安装更省事。这篇按官方脚本、日常 compose、挂载、环境变量的顺序走，最后给 5 个常见坑。

先确认 Docker 装好了

不管什么系统，先在终端查一下 Docker 在不在：

docker --version
docker compose version

两条都有输出就行。没装的话：macOS 和 Windows 装 Docker Desktop（图形界面，开箱即用）；Linux 装 docker 引擎加 compose 插件。Windows 上 Docker Desktop 会要求开 WSL2，按它的提示走即可。

路线一：官方脚本 + 现成镜像（推荐）

官方镜像发在 GitHub Container Registry 上，Docker Hub 有一份同步的镜像仓（openclaw/openclaw）。认准这两个来源，别去拉第三方转存的——它们的更新时间和保留策略跟官方对不上。

但别急着手写 docker run。官方仓库里自带一份 docker-compose.yml 和一个 scripts/docker/setup.sh，脚本会替你把 .env 同步好、修好目录权限、跑一遍引导向导（问你 API key、生成 Gateway token 写进 .env）、最后用 compose 把容器拉起来。拉仓库只是为了拿这两个文件，不是要你编译什么：

git clone https://github.com/openclaw/openclaw.git
cd openclaw

# 告诉脚本用现成镜像，别在本机从源码构建（构建要 2G 以上内存，1G 小机会被 OOM 杀掉）
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

跑完浏览器开 http://127.0.0.1:18789/，把脚本写进 .env 的那个 token 贴进设置里，控制台就通了。忘了 token 在哪，让它再打一遍 URL：

docker compose run --rm openclaw-cli dashboard --no-open

两个关键事实记一下：龙虾的 Gateway 听的是 18789 端口（不是网上常见的 8080）；镜像里进程以 node 用户（uid 1000）身份跑，后面挂载目录的权限坑就从这来。

路线二：自己管 compose（日常起停）

脚本跑过一次之后，日常起停就是标准的 compose 命令，在仓库根目录下敲：

# 起 Gateway（-d 后台）
docker compose up -d openclaw-gateway

# 看日志，确认起来了
docker compose logs -f openclaw-gateway

# 停服务
docker compose down

想在容器里跑龙虾的命令行（比如接 Telegram、看状态），不用进容器，借 openclaw-cli 这个服务一次性跑：

docker compose run --rm openclaw-cli channels add --channel telegram --token "你的bot token"
docker compose run --rm openclaw-cli doctor --json

官方的 compose 文件已经把 restart、端口、挂载都写好了，新手不用自己改。真要定制（多挂一个目录、改时区），用 OPENCLAW_EXTRA_MOUNTS、OPENCLAW_TZ 这类环境变量喂给 setup 脚本，比手改 yml 稳。

restart: unless-stopped 这一行很实用——机器重启后容器会自动拉起来，不用你手动开。

环境变量：把“大脑”接上

龙虾本体没智商，得告诉它用哪个模型。setup 脚本跑引导时已经问过你一次 key 了，这里讲的是事后想改、想换怎么办。这件事分在两个文件里：密钥进仓库根目录的 .env（compose 会把它喂给容器），模型名进挂载出来的 openclaw.json。密钥是按服务商各自命名的，没有通用的 API_KEY；脚本生成的 OPENCLAW_GATEWAY_TOKEN 也在这个文件里，别删：

# 走云端 API，用哪家就填哪一行
ANTHROPIC_API_KEY=sk-ant-你的密钥
# OPENAI_API_KEY=sk-...
OPENCLAW_GATEWAY_TOKEN=脚本生成的，留着

再到挂进去的 openclaw.json 里指定模型，键是 agents.defaults.model.primary，值是“服务商/模型名”：

{ agents: { defaults: { model: { primary: "anthropic/claude-opus-5" } } } }

要接宿主机上跑的本地模型，就在同一个文件里把本地服务登记成服务商——注意 baseUrl 那一行：

{
  agents: {
    defaults: { model: { primary: "local/你的本地模型" } }
  },
  models: {
    mode: "merge",
    providers: {
      local: {
        baseUrl: "http://host.docker.internal:11434/v1",  // 不是 localhost
        apiKey: "ollama-local",
        api: "openai-completions",
        models: [
          { id: "你的本地模型", name: "本地模型", contextWindow: 120000, maxTokens: 8192 }
        ]
      }
    }
  }
}

注意一个容器里的坑：容器内的 localhost 指的是容器自己，不是你本机。要让容器访问本机上跑的本地模型服务，地址得写 host.docker.internal，不能写 localhost。这是新手最常栽的地方。

挂载：哪些目录一定要挂出来

容器是“用完即弃”的，删了重建里面写的东西就没了。官方的 compose 文件已经把这几个目录挂到了本机，你要做的是知道它们在哪、别乱删：

配置目录：本机的 OPENCLAW_CONFIG_DIR 挂到容器内的 /home/node/.openclaw——openclaw.json、各 agent 的凭据、会话数据都在这。
工作区：本机的 OPENCLAW_WORKSPACE_DIR 挂到容器内的 /home/node/.openclaw/workspace——龙虾的记忆、产出文件、你让它操作的东西都在这。
想让它碰的别的目录：用 OPENCLAW_EXTRA_MOUNTS 多挂几条，格式是 本机路径:容器路径，逗号分隔。

这两个变量不设的话，脚本会在你的家目录下挑个默认位置；在服务器上长期跑，建议显式设好、写进 shell 的启动文件里，免得换个终端就“找不到数据”。没挂的目录里写的东西，跟容器一起灰飞烟灭。

避坑提示 用 setup 脚本起龙虾，第一次的时间大头在拉镜像上（镜像不小），拉完之后起容器很快，浏览器开 127.0.0.1:18789 就能进界面。最容易踩的坑是模型地址：如果你在容器里把地址写成 localhost:11434 去接宿主机上的本地服务，容器是连不上的——容器里的 localhost 指的是容器自己。要接宿主机服务，得改成 host.docker.internal，而且宿主机上的 Ollama / LM Studio 要监听 0.0.0.0 而不是只听回环（比如 OLLAMA_HOST=0.0.0.0:11434 ollama serve），不然容器那头来了请求它也不接。这两条几乎人人会撞一次，记下来能省半小时排查。

常见坑 5 条

1. 端口已被占用（port is already allocated）

原因：本机 18789 被别的程序占了——常见是你之前在本机直接装过龙虾、它的 Gateway 还在跑。解决：lsof -i :18789 查出是谁，停掉它；或者改 compose 里的端口映射，左边本机端口、右边容器端口，改左边就行。

2. 容器内连不上本机的本地模型

原因：地址写成了 localhost，或者宿主机上的模型服务只听回环。解决：地址改成 host.docker.internal；官方 compose 在 Linux 上已经把这个别名映射到宿主机了，自己写 docker run 的话要加 --add-host=host.docker.internal:host-gateway；宿主机服务绑到 0.0.0.0。

3. 改了 .env 不生效

原因：环境变量是容器启动时读的，光改文件不重启没用。解决：docker compose up -d openclaw-gateway 再跑一遍，它会用新配置重建容器。

4. 挂载目录报权限错误（EACCES）

原因：镜像里进程以 uid 1000 的 node 用户跑，你本机挂出来的目录却是别的用户（常见是 root）的。解决：把两个挂载目录 chown 给 1000：sudo chown -R 1000:1000 配置目录工作区目录。

5. 拉镜像超时，或构建时被杀（exit 137）

原因：前者是默认镜像仓库在境外、慢；后者是你没设 OPENCLAW_IMAGE，脚本在本机从源码构建镜像，1G 内存的机器扛不住。解决：拉不动就换 Docker Hub 那份同步镜像（OPENCLAW_IMAGE="openclaw/openclaw:latest"）或给 Docker 配国内加速；被杀就老老实实用现成镜像，别在小机器上构建。

常见问题

用 Docker 跑龙虾和直接装有什么区别？: 最大区别是干净。Docker 把依赖全封在容器里，不碰本机环境，删容器就等于卸干净。代价是镜像占几个 G、首次拉镜像慢。机器上已有别的项目、怕版本打架时用 Docker 最省心。
容器一关，配置和数据会丢吗？: 看有没有挂载。用 volumes 把配置和数据目录挂到本机，删了重建也不丢；没挂的话容器内写的东西会跟着没。所以 .env 和数据目录一定要挂出来。
容器里能调用本机的浏览器或文件吗？: 文件可以，把本机目录挂进容器即可。本机图形浏览器默认进不去容器，浏览器自动化用容器自带的无头浏览器。要操作本机桌面软件的场景，建议直接本地装。