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

Docker 把依赖封在容器里，不碰本机的 Node 环境；按官方脚本装的，配置和工作区在挂载出来的本机目录里，删容器不会删掉它们。代价是镜像要占磁盘空间。官方把 Docker 定位成可选项：要隔离环境、或机器上不想装 Node 时用它，本机能直接装的走普通安装。

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

按官方脚本装的不会丢：官方 compose 已经把配置目录和工作区挂到了本机，.env 本来就在宿主机的仓库根目录里，不在容器里。自己写 docker run 的才要手动把这两个目录挂出来，没挂的话容器里写的东西会跟着容器一起删掉。

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

文件可以，把本机目录挂进容器即可。本机图形浏览器默认进不去容器，浏览器自动化要换成带 -browser 后缀的镜像变体（如 latest-browser），默认镜像里不带浏览器。要操作本机桌面软件的场景，建议直接本地装。

教程 · 部署

用 Docker 部署 OpenClaw 龙虾：安装步骤与常见问题

钳叔 · 龙虾AI 编辑部 · 2026-06-07 发布 · 2026-10-08 更新

本机装龙虾要先备好 Node，再往全局装一个包，机器上已经有别的 Node 项目的话，版本可能打架。Docker 把这些依赖封进容器——用官方脚本拉一个现成镜像，跑完引导，龙虾就起来了，不碰你本机的 Node 环境。官方 Docker 文档把 Docker 定位成“可选项”：要隔离、要一次性环境、或者机器上不想装 Node 时才用它；本机能直接装的，走普通安装。

系统: Docker
发布日期: 2026-06-07
更新日期: 2026-10-08

装之前：确认 Docker 和 Compose 能用

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

docker --version
docker compose version

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

用官方 setup 脚本加现成镜像安装（推荐）

官方镜像发在 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

# 告诉脚本用现成镜像，别在本机从源码构建（官方文档写本机构建至少要 6 GB 内存，现成镜像不受这条限制）
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh

latest 这个标签会跟着稳定版往前移。要把版本固定住，就把它换成具体的版本号标签，官方文档举的例子是 2026.9.3，写出来是 ghcr.io/openclaw/openclaw:2026.9.3；要升级时再手动改标签。已经跑起来的安装，改的是仓库根目录 .env 里的 OPENCLAW_IMAGE，改完执行 docker compose pull openclaw-gateway openclaw-cli 和 docker compose up -d openclaw-gateway；不要为了换镜像在一个空的 shell 里重跑 setup 脚本，官方文档写明它会按当前 shell 和默认值重写 .env。

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

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

两个关键事实记一下：龙虾的 Gateway 听的是 18789 端口；镜像里进程以 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 这一行很实用——机器重启后容器会自动拉起来，不用你手动开。

API key 和模型填在哪，怎么接宿主机上的 Ollama

OpenClaw 自己不含模型，要指定用哪个。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-5" } } } }

要接宿主机上跑的 Ollama，就在同一个文件里把它登记成服务商。OpenClaw 走的是 Ollama 的原生接口，baseUrl 只写到端口，后面不要加 /v1——官方 Ollama 文档写明，加了会让工具调用失效，模型可能把工具调用的 JSON 当成普通文字吐出来：

{
  models: {
    providers: {
      ollama: {
        api: "ollama",
        baseUrl: "http://host.docker.internal:11434",  // 不是 localhost，也不带 /v1
        apiKey: "ollama-local",
        models: [{ id: "你的本地模型", name: "本地模型" }]
      }
    }
  }
}

登记好以后把它设成默认模型：在同一个 openclaw.json 里把 agents.defaults.model.primary 写成 "ollama/<模型名>"，或者借 compose 里的 CLI 跑 docker compose run --rm openclaw-cli models set ollama/<模型名>。<模型名> 就是上面 id 里的名字，要和宿主机上 ollama list 显示的完全一致。

容器内的 localhost 指的是容器自己，不是你本机。要让容器访问本机上跑的本地模型服务，地址得写 host.docker.internal，不能写 localhost。

光改地址还不够：宿主机上的 Ollama / LM Studio 要监听 0.0.0.0 而不是只听回环（官方 Docker 文档的 Host local providers 一节给 Ollama 的写法是 OLLAMA_HOST=0.0.0.0:11434 ollama serve）。监听 0.0.0.0 等于让这台机器的所有网卡都接 11434 的请求：在云主机上，要同时用防火墙或安全组把 11434 挡在公网之外。

照上面这样只写 id 和 name 时，上下文长度由 Ollama 那一侧定，装好后用 ollama ps 看 CONTEXT 一栏实际分到多少。默认值是多少、想在 OpenClaw 这边调大时 contextTokens 和 params.num_ctx 怎么一起改，见显存不够的 6 个办法里的第 4 条；接好之后能聊天却不动手的，按接 Ollama 不调用工具的排查步骤逐项查。

挂载：配置和工作区在本机的哪个目录

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

配置目录：本机的 OPENCLAW_CONFIG_DIR 挂到容器内的 /home/node/.openclaw——openclaw.json、各 agent 的凭据、会话数据都在这。这个目录先别放在 FUSE 挂载上，比如 NAS 上映射进容器的目录。有用户报告，状态目录放在这类挂载上时，升级会在 Doctor 那一步失败（问题报告 #163179）。修复已经提交（#164123），但截至 2026 年 10 月 7 日还没进 latest 指向的 2026.9.8。已经放在上面的先不要升级，详情见 OpenClaw 2026.9.8 更新说明里讲 FUSE 状态目录的一节。
工作区：本机的 OPENCLAW_WORKSPACE_DIR 挂到容器内的 /home/node/.openclaw/workspace——龙虾的记忆、产出文件、你让它操作的东西都在这。
想让它碰的别的目录：用 OPENCLAW_EXTRA_MOUNTS 多挂几条，格式是 本机路径:容器路径，逗号分隔。

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

Docker 部署 OpenClaw 的 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（云主机上记得用防火墙或安全组挡住 11434，别让它对公网开放）。

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，脚本在本机从源码构建镜像，而官方文档写本机构建至少要 6 GB 内存。解决：拉不动就换 Docker Hub 那份同步镜像（OPENCLAW_IMAGE="openclaw/openclaw:latest"）；被杀就用现成镜像，内存不到 6 GB 的机器别在本机构建。

常见问题

用 Docker 跑龙虾和直接装有什么区别？: Docker 把依赖封在容器里，不碰本机的 Node 环境；按官方脚本装的，配置和工作区在挂载出来的本机目录里，删容器不会删掉它们。代价是镜像要占磁盘空间。官方把 Docker 定位成可选项：要隔离环境、或机器上不想装 Node 时用它，本机能直接装的走普通安装。
容器一关，配置和数据会丢吗？: 按官方脚本装的不会丢：官方 compose 已经把配置目录和工作区挂到了本机，.env 本来就在宿主机的仓库根目录里，不在容器里。自己写 docker run 的才要手动把这两个目录挂出来，没挂的话容器里写的东西会跟着容器一起删掉。
容器里能调用本机的浏览器或文件吗？: 文件可以，把本机目录挂进容器即可。本机图形浏览器默认进不去容器，浏览器自动化要换成带 -browser 后缀的镜像变体（如 latest-browser），默认镜像里不带浏览器。要操作本机桌面软件的场景，建议直接本地装。