[OpenClaw 文档]安装--安装方式

本文档汇总了 OpenClaw 官方文档站 安装 > 安装方式 子模块下的全部 4 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 Docker

原文：https://docs.openclaw.ai/zh-CN/install/docker

Docker 是可选的。只有在你需要容器化 Gateway 网关，或需要验证 Docker 流程时才使用它。

Docker 适合我吗？

• 是：你想要一个隔离、可丢弃的 Gateway 网关环境，或想在没有本地安装的主机上运行 OpenClaw。
• 否：你在自己的机器上运行，只想要最快的开发循环。请改用常规安装流程。
• 沙箱注意事项：启用沙箱隔离时，默认沙箱后端会使用 Docker，但沙箱隔离默认关闭，并且不要求完整 Gateway 网关在 Docker 中运行。SSH 和 OpenShell 沙箱后端也可用。参见 沙箱隔离。

前置条件

• Docker Desktop（或 Docker Engine）+ Docker Compose v2
• 镜像构建至少需要 2 GB RAM（在 1 GB 主机上，pnpm install 可能会因 OOM 被终止并以 137 退出）
• 足够存放镜像和日志的磁盘空间
• 如果在 VPS/公网主机上运行，请查看
  网络暴露的安全加固，
  尤其是 Docker DOCKER-USER 防火墙策略。

容器化 Gateway 网关

在仓库根目录运行设置脚本：

```bash
./scripts/docker/setup.sh
```

这会在本地构建 Gateway 网关镜像。要改用预构建镜像：

```bash
export OPENCLAW_IMAGE="ghcr.io/openclaw/openclaw:latest"
./scripts/docker/setup.sh
```

预构建镜像发布在
[GitHub Container Registry](https://github.com/openclaw/openclaw/pkgs/container/openclaw)。
常用标签：`main`、`latest`、`<version>`（例如 `2026.2.26`）。

设置脚本会自动运行新手引导。它会：

- 提示输入提供商 API key
- 生成 Gateway 网关令牌并写入 `.env`
- 创建 auth-profile 密钥目录
- 通过 Docker Compose 启动 Gateway 网关

设置期间，启动前的新手引导和配置写入会直接通过
`openclaw-gateway` 运行。`openclaw-cli` 用于在
Gateway 网关容器已经存在后运行的命令。

在浏览器中打开 http://127.0.0.1:18789/，并将配置好的
共享密钥粘贴到设置中。设置脚本默认会向 .env 写入令牌；
如果你将容器配置切换为密码认证，请改用该密码。

还需要再次查看 URL？

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

使用 CLI 容器添加消息渠道：

```bash
# WhatsApp (QR)
docker compose run --rm openclaw-cli channels login

# Telegram
docker compose run --rm openclaw-cli channels add --channel telegram --token "<token>"

# Discord
docker compose run --rm openclaw-cli channels add --channel discord --token "<token>"
```

文档：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)

手动流程

如果你更喜欢自己运行每个步骤，而不是使用设置脚本：

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-gateway

请从仓库根目录运行 docker compose。如果你启用了 OPENCLAW_EXTRA_MOUNTS
或 OPENCLAW_HOME_VOLUME，设置脚本会写入 docker-compose.extra.yml；
请用 -f docker-compose.yml -f docker-compose.extra.yml 将其包含进来。

因为 openclaw-cli 共享 openclaw-gateway 的网络命名空间，所以它是一个
启动后工具。在 docker compose up -d openclaw-gateway 之前，请通过
带有 --no-deps --entrypoint node 的 openclaw-gateway 运行新手引导
和设置时配置写入。

环境变量

设置脚本接受以下可选环境变量：

维护者可以通过将一个插件源目录挂载到它的打包源路径上，来针对打包镜像测试
内置插件源代码，例如
OPENCLAW_EXTRA_MOUNTS=/path/to/fork/extensions/synology-chat:/app/extensions/synology-chat:ro。
该挂载的源目录会覆盖同一插件 id 对应的已编译
/app/dist/extensions/synology-chat 包。

可观测性

OpenTelemetry 导出是从 Gateway 网关容器向你的 OTLP
收集器发出的出站连接。它不需要发布 Docker 端口。如果你在本地构建镜像，
并希望内置 OpenTelemetry exporter 在镜像内可用，请包含它的运行时依赖：

export OPENCLAW_EXTENSIONS="diagnostics-otel"
export OTEL_EXPORTER_OTLP_ENDPOINT="http://otel-collector:4318"
export OTEL_SERVICE_NAME="openclaw-gateway"
./scripts/docker/setup.sh

在打包的 Docker 安装中启用导出之前，请从 ClawHub 安装官方
@openclaw/diagnostics-otel 插件。自定义源码构建镜像仍然可以通过
OPENCLAW_EXTENSIONS=diagnostics-otel 包含本地插件源代码。要启用导出，
请在配置中允许并启用 diagnostics-otel 插件，然后设置
diagnostics.otel.enabled=true，或使用 OpenTelemetry
导出 中的配置示例。收集器认证标头通过
diagnostics.otel.headers 配置，而不是通过 Docker 环境变量配置。

Prometheus 指标使用已经发布的 Gateway 网关端口。安装
clawhub:@openclaw/diagnostics-prometheus，启用
diagnostics-prometheus 插件，然后抓取：

http://<gateway-host>:18789/api/diagnostics/prometheus

该路由受 Gateway 网关认证保护。不要暴露单独的公开 /metrics 端口，
也不要暴露未认证的反向代理路径。参见
Prometheus 指标。

健康检查

容器探针端点（无需认证）：

curl -fsS http://127.0.0.1:18789/healthz   # liveness
curl -fsS http://127.0.0.1:18789/readyz     # readiness

Docker 镜像包含内置 HEALTHCHECK，它会 ping /healthz。
如果检查持续失败，Docker 会将容器标记为 unhealthy，
编排系统可以重启或替换它。

经过认证的深度健康快照：

docker compose exec openclaw-gateway node dist/index.js health --token "$OPENCLAW_GATEWAY_TOKEN"

LAN 与 loopback

scripts/docker/setup.sh 默认设置 OPENCLAW_GATEWAY_BIND=lan，因此通过
Docker 端口发布可以让主机访问 http://127.0.0.1:18789。

• lan（默认）：主机浏览器和主机 CLI 可以访问已发布的 Gateway 网关端口。
• loopback：只有容器网络命名空间内的进程可以直接访问
  Gateway 网关。

请使用 gateway.bind 中的绑定模式值（lan / loopback / custom /
tailnet / auto），不要使用 0.0.0.0 或 127.0.0.1 这样的主机别名。

主机本地提供商

当 OpenClaw 在 Docker 中运行时，容器内的 127.0.0.1 是容器
本身，而不是你的主机。对于在主机上运行的 AI 提供商，请使用
host.docker.internal：

内置 Docker 设置会将这些主机 URL 用作 LM Studio 和 Ollama
的新手引导默认值，并且 docker-compose.yml 会在 Linux Docker Engine
上将 host.docker.internal 映射到 Docker 的主机网关。Docker Desktop
已经在 macOS 和 Windows 上提供相同的主机名。

主机服务还必须监听 Docker 可访问的地址：

lms server start --port 1234 --bind 0.0.0.0
OLLAMA_HOST=0.0.0.0:11434 ollama serve

如果你使用自己的 Compose 文件或 docker run 命令，请自行添加相同的
主机映射，例如
--add-host=host.docker.internal:host-gateway。

Bonjour / mDNS

Docker 桥接网络通常无法可靠转发 Bonjour/mDNS 多播
（224.0.0.251:5353）。因此，内置 Compose 设置默认使用
OPENCLAW_DISABLE_BONJOUR=1，避免 Gateway 网关在桥接网络丢弃多播流量时
陷入崩溃循环或反复重启广播。

对 Docker 主机使用已发布的 Gateway 网关 URL、Tailscale 或广域 DNS-SD。
仅在使用主机网络、macvlan 或另一个已知 mDNS 多播可用的网络时，才设置
OPENCLAW_DISABLE_BONJOUR=0。

关于易错点和故障排除，请参见 Bonjour 设备发现。

存储和持久化

Docker Compose 会将 OPENCLAW_CONFIG_DIR 绑定挂载到 /home/node/.openclaw，
将 OPENCLAW_WORKSPACE_DIR 绑定挂载到 /home/node/.openclaw/workspace，
并将 OPENCLAW_AUTH_PROFILE_SECRET_DIR 绑定挂载到 /home/node/.config/openclaw，
因此这些路径会在容器替换后保留。当任一变量未设置时，内置
docker-compose.yml 会回退到 ${HOME} 下；如果 HOME 本身也缺失，
则回退到 /tmp。这可以避免 docker compose up 在裸环境中发出空源
卷规范。

OpenClaw 会在该挂载的配置目录中保存：

• 用于行为配置的 openclaw.json
• 用于存储提供商 OAuth/API-key 凭证的 agents/<agentId>/agent/auth-profiles.json
• 用于环境变量支持的运行时密钥的 .env，例如 OPENCLAW_GATEWAY_TOKEN

auth-profile 密钥目录会存储用于 OAuth 支持的认证配置令牌材料的本地加密密钥。
请将它与你的 Docker 主机状态保存在一起，但与 OPENCLAW_CONFIG_DIR 分开。

已安装的可下载插件会把其包状态存储在已挂载的 OpenClaw home 下，因此插件安装记录和包根目录会在容器替换后保留下来。Gateway 网关启动不会生成内置插件依赖树。

有关 VM 部署的完整持久化详情，请参阅
Docker VM 运行时 - 持久化位置。

磁盘增长热点：关注 media/、会话 JSONL 文件、cron/runs/*.jsonl、已安装插件包根目录，以及 /tmp/openclaw/ 下的滚动文件日志。

Shell 辅助脚本（可选）

为了更轻松地进行日常 Docker 管理，请安装 ClawDock：

mkdir -p ~/.clawdock && curl -sL https://raw.githubusercontent.com/openclaw/openclaw/main/scripts/clawdock/clawdock-helpers.sh -o ~/.clawdock/clawdock-helpers.sh
echo 'source ~/.clawdock/clawdock-helpers.sh' >> ~/.zshrc && source ~/.zshrc

如果你曾从旧的 scripts/shell-helpers/clawdock-helpers.sh raw 路径安装 ClawDock，请重新运行上面的安装命令，让你的本地辅助文件跟踪新位置。

然后使用 clawdock-start、clawdock-stop、clawdock-dashboard 等命令。运行
clawdock-help 查看所有命令。
请参阅 ClawDock 获取完整辅助脚本指南。

bash
export OPENCLAW_SANDBOX=1
./scripts/docker/setup.sh

自定义套接字路径（例如 rootless Docker）：

```bash
export OPENCLAW_SANDBOX=1
export OPENCLAW_DOCKER_SOCKET=/run/user/1000/docker.sock
./scripts/docker/setup.sh
```

该脚本只会在沙箱前置条件通过后挂载 `docker.sock`。如果沙箱设置无法完成，脚本会将 `agents.defaults.sandbox.mode` 重置为 `off`。当 OpenClaw 沙箱处于活动状态时，Codex code-mode 轮次仍受 Codex `workspace-write` 约束；不要把宿主 Docker 套接字挂载到 Agent 沙箱容器中。

使用 -T 禁用 Compose 伪 TTY 分配：

```bash
docker compose run -T --rm openclaw-cli gateway probe
docker compose run -T --rm openclaw-cli devices list --json
```

openclaw-cli 使用 network_mode: "service:openclaw-gateway"，这样 CLI 命令可以通过 127.0.0.1 访问 Gateway 网关。请把这视为共享信任边界。compose 配置会在 openclaw-gateway 和 openclaw-cli 上删除 NET_RAW/NET_ADMIN 并启用 no-new-privileges。

一些 Docker Desktop 设置在删除 NET_RAW 后，会导致共享网络中的 openclaw-cli sidecar DNS 查询失败，表现为 npm 支持的命令（例如 openclaw plugins install）期间出现 EAI_AGAIN。正常 Gateway 网关运行请保留默认的强化 compose 文件。下面的本地 override 会通过恢复 Docker 默认 capabilities 来放宽 CLI 容器的安全态势，因此只应将其用于需要访问包注册表的一次性 CLI 命令，不要作为你的默认 Compose 调用：

```bash
printf '%s\n' \
  'services:' \
  '  openclaw-cli:' \
  '    cap_drop: !reset []' \
  > docker-compose.cli-no-dropped-caps.local.yml

docker compose -f docker-compose.yml -f docker-compose.cli-no-dropped-caps.local.yml run --rm openclaw-cli plugins install <package>
```

如果你已经创建了长期运行的 `openclaw-cli` 容器，请使用相同的 override 重新创建它。`docker compose exec` 和 `docker exec` 无法更改已创建容器上的 Linux capabilities。

镜像以 node（uid 1000）身份运行。如果你在 /home/node/.openclaw 上看到权限错误，请确保你的宿主绑定挂载由 uid 1000 拥有：

```bash
sudo chown -R 1000:1000 /path/to/openclaw-config /path/to/openclaw-workspace
```

同样的不匹配可能表现为插件警告，例如
`blocked plugin candidate: suspicious ownership (... uid=1000, expected uid=0 or root)`
后面跟着 `plugin present but blocked`。这表示进程 uid 与已挂载的插件目录所有者不一致。建议以默认 uid 1000 运行容器，并修复绑定挂载的所有权。只有在你打算长期以 root 身份运行 OpenClaw 时，才将 `/path/to/openclaw-config/npm` chown 为 `root:root`。

调整 Dockerfile 顺序，让依赖层可以被缓存。这样除非 lockfile 发生变化，否则可避免重新运行 pnpm install：

```dockerfile
FROM node:24-bookworm
RUN curl -fsSL https://bun.sh/install | bash
ENV PATH="/root/.bun/bin:${PATH}"
RUN corepack enable
WORKDIR /app
COPY package.json pnpm-lock.yaml pnpm-workspace.yaml .npmrc ./
COPY ui/package.json ./ui/package.json
COPY scripts ./scripts
RUN pnpm install --frozen-lockfile
COPY . .
RUN pnpm build
RUN pnpm ui:install
RUN pnpm ui:build
ENV NODE_ENV=production
CMD ["node","dist/index.js"]
```

默认镜像以安全优先，并以非 root node 身份运行。如需功能更完整的容器：

1. **持久化 `/home/node`**：`export OPENCLAW_HOME_VOLUME="openclaw_home"`
2. **预置系统依赖**：`export OPENCLAW_DOCKER_APT_PACKAGES="git curl jq"`
3. **预置 Playwright Chromium**：`export OPENCLAW_INSTALL_BROWSER=1`
4. **或将 Playwright 浏览器安装到持久化卷中**：
   ```bash
   docker compose run --rm openclaw-cli \
     node /app/node_modules/playwright-core/cli.js install chromium
   ```
5. **持久化浏览器下载**：使用 `OPENCLAW_HOME_VOLUME` 或 `OPENCLAW_EXTRA_MOUNTS`。OpenClaw 会在 Linux 上自动检测 Docker 镜像中由 Playwright 管理的 Chromium。

如果你在向导中选择 OpenAI Codex OAuth，它会打开一个浏览器 URL。在 Docker 或无头设置中，复制你最终到达的完整重定向 URL，并将其粘贴回向导以完成认证。

主 Docker 运行时镜像使用 node:24-bookworm-slim，并包含 tini 作为入口点 init 进程（PID 1），以确保长期运行容器中的僵尸进程会被回收，信号也会被正确处理。它发布 OCI 基础镜像注解，包括 org.opencontainers.image.base.name、
org.opencontainers.image.source 以及其他注解。Node 基础 digest 会通过 Dependabot Docker 基础镜像 PR 刷新；发布构建不会运行发行版升级层。请参阅
OCI 镜像注解。

在 VPS 上运行？

请参阅 Hetzner（Docker VPS） 和
Docker VM 运行时，了解共享 VM 部署步骤，包括二进制预置、持久化和更新。

Agent 沙箱

当使用 Docker 后端启用 agents.defaults.sandbox 时，Gateway 网关会在隔离的 Docker 容器内运行 Agent 工具执行（shell、文件读写等），而 Gateway 网关本身仍留在宿主机上。这会在不将整个 Gateway 网关容器化的情况下，为不受信任或多租户 Agent 会话提供一道硬隔离墙。

沙箱范围可以是按 Agent（默认）、按会话或共享。每个范围都有自己的工作区，挂载在 /workspace。你还可以配置允许/拒绝工具策略、网络隔离、资源限制和浏览器容器。

有关完整配置、镜像、安全说明和多 Agent 配置文件，请参阅：

• 沙箱隔离 -- 完整沙箱参考
• OpenShell -- 对沙箱容器的交互式 shell 访问
• 多 Agent 沙盒和工具 -- 按 Agent 覆盖

快速启用

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
      },
    },
  },
}

构建默认沙箱镜像（从源码 checkout）：

scripts/sandbox-setup.sh

对于没有源码 checkout 的 npm 安装，请参阅 沙箱隔离 § 镜像和设置，获取内联 docker build 命令。

故障排除

使用
scripts/sandbox-setup.sh
（源码 checkout）构建沙箱镜像，或使用 沙箱隔离 § 镜像和设置 中的内联 docker build 命令（npm 安装），
或将 agents.defaults.sandbox.docker.image 设置为你的自定义镜像。
容器会按会话在需要时自动创建。

将 docker.user 设置为与你挂载工作区所有权匹配的 UID:GID，或 chown 工作区文件夹。

OpenClaw 使用 sh -lc（login shell）运行命令，它会 source
/etc/profile 并可能重置 PATH。设置 docker.env.PATH 来前置你的自定义工具路径，或在你的 Dockerfile 中的 /etc/profile.d/ 下添加脚本。

VM 至少需要 2 GB RAM。使用更大的机器规格后重试。

获取新的 dashboard 链接并批准浏览器设备：

```bash
docker compose run --rm openclaw-cli dashboard --no-open
docker compose run --rm openclaw-cli devices list
docker compose run --rm openclaw-cli devices approve <requestId>
```

更多详情：[Dashboard](/zh-CN/web/dashboard)、[Devices](/zh-CN/cli/devices)。

重置 Gateway 网关模式和绑定：

```bash
docker compose run --rm openclaw-cli config set --batch-json '[{"path":"gateway.mode","value":"local"},{"path":"gateway.bind","value":"lan"}]'
docker compose run --rm openclaw-cli devices list --url ws://127.0.0.1:18789
```

相关

• 安装概览 — 所有安装方法
• Podman — Docker 的 Podman 替代方案
• ClawDock — Docker Compose 社区设置
• 更新 — 让 OpenClaw 保持最新
• 配置 — 安装后的 Gateway 网关配置

📄 Nix

原文：https://docs.openclaw.ai/zh-CN/install/nix

声明式安装 OpenClaw：使用 nix-openclaw，这是第一方、功能齐备的 Home Manager 模块。

nix-openclaw 仓库是 Nix 安装的权威来源。本页是快速概览。

你将获得什么

• Gateway 网关 + macOS 应用 + 工具（whisper、spotify、cameras）-- 全部固定版本
• 重启后仍会保留的 launchd 服务
• 带声明式配置的插件系统
• 即时回滚：home-manager switch --rollback

快速开始

如果尚未安装 Nix，请按照 Determinate Nix 安装器说明操作。


使用 nix-openclaw 仓库中的 agent 优先模板：
bash
mkdir -p ~/code/openclaw-local
# Copy templates/agent-first/flake.nix from the nix-openclaw repo


设置你的消息传递 bot 令牌和模型提供商 API key。放在 ~/.secrets/ 下的纯文件即可。


bash
home-manager switch


确认 launchd 服务正在运行，并且你的 bot 会响应消息。

请参阅 nix-openclaw README，了解完整的模块选项和示例。

Nix 模式运行时行为

设置 OPENCLAW_NIX_MODE=1 时（使用 nix-openclaw 会自动设置），OpenClaw 会进入用于 Nix 托管安装的确定性模式。其他 Nix 包也可以设置同一模式；nix-openclaw 是第一方参考实现。

你也可以手动设置：

export OPENCLAW_NIX_MODE=1

在 macOS 上，GUI 应用不会自动继承 shell 环境变量。请改用 defaults 启用 Nix 模式：

defaults write ai.openclaw.mac openclaw.nixMode -bool true

Nix 模式会改变什么

• 自动安装和自我变更流程会被禁用
• openclaw.json 会被视为不可变。启动时派生的默认值只保留在运行时，并且设置、新手引导、会修改配置的 openclaw update、插件安装/更新/卸载/启用、doctor --fix、doctor --generate-gateway-token 和 openclaw config set 等配置写入器都会拒绝编辑该文件。
• Agent 应改为编辑 Nix 源。对于 nix-openclaw，请使用 agent 优先的快速开始，并在 programs.openclaw.config 或 instances.<name>.config 下设置配置。
• 缺失依赖会显示 Nix 专用的修复消息
• UI 会显示只读 Nix 模式横幅

配置和状态路径

OpenClaw 从 OPENCLAW_CONFIG_PATH 读取 JSON5 配置，并将可变数据存储在 OPENCLAW_STATE_DIR 中。在 Nix 下运行时，请将这些路径显式设置为 Nix 托管位置，确保运行时状态和配置不会进入不可变 store。

服务 PATH 发现

launchd/systemd Gateway 网关服务会自动发现 Nix profile 二进制文件，因此
通过 shell 调用 nix 安装可执行文件的插件和工具无需
手动设置 PATH 即可工作：

• 设置 NIX_PROFILES 时，每个条目都会按
  从右到左的优先级加入服务 PATH（与 Nix shell 优先级一致 -- 最右侧获胜）。
• 未设置 NIX_PROFILES 时，会将 ~/.nix-profile/bin 作为回退加入。

这同时适用于 macOS launchd 和 Linux systemd 服务环境。

相关

权威 Home Manager 模块和完整设置指南。


非 Nix CLI 设置演练。


作为非 Nix 替代方案的容器化设置。


随包一起更新由 Home Manager 管理的安装。

📄 Ansible

原文：https://docs.openclaw.ai/zh-CN/install/ansible

使用 openclaw-ansible 将 OpenClaw 部署到生产服务器，这是一个采用安全优先架构的自动化安装器。

openclaw-ansible 仓库是 Ansible 部署的事实来源。本页是快速概览。

前提条件

你会获得什么

• 防火墙优先的安全性 -- UFW + Docker 隔离（仅 SSH + Tailscale 可访问）
• Tailscale VPN -- 无需公开暴露服务即可安全远程访问
• Docker -- 隔离的沙箱容器，仅 localhost 绑定
• 纵深防御 -- 4 层安全架构
• Systemd 集成 -- 启动时自动启动并加固
• 一条命令完成设置 -- 数分钟内完成部署

快速开始

一条命令安装：

curl -fsSL https://raw.githubusercontent.com/openclaw/openclaw-ansible/main/install.sh | bash

会安装什么

Ansible playbook 会安装并配置：

1. Tailscale -- 用于安全远程访问的 mesh VPN
2. UFW 防火墙 -- 仅开放 SSH + Tailscale 端口
3. Docker CE + Compose V2 -- 用于默认的智能体沙箱后端
4. Node.js 24 + pnpm -- 运行时依赖（Node 22 LTS，目前为 22.16+，仍受支持）
5. OpenClaw -- 基于主机运行，不容器化
6. Systemd 服务 -- 通过安全加固实现自动启动

Gateway 网关直接在主机上运行（不在 Docker 中）。智能体沙箱隔离是
可选的；此 playbook 会安装 Docker，因为它是默认沙箱
后端。详情和其他后端请参阅 沙箱隔离。

安装后设置

bash
sudo -i -u openclaw


安装后脚本会引导你配置 OpenClaw 设置。


登录 WhatsApp、Telegram、Discord 或 Signal：
bash
openclaw channels login


bash
sudo systemctl status openclaw
sudo journalctl -u openclaw -f


加入你的 VPN mesh 以进行安全远程访问。

快捷命令

# Check service status
sudo systemctl status openclaw

# View live logs
sudo journalctl -u openclaw -f

# Restart gateway
sudo systemctl restart openclaw

# Provider login (run as openclaw user)
sudo -i -u openclaw
openclaw channels login

安全架构

该部署使用 4 层防御模型：

1. 防火墙 (UFW) -- 仅公开暴露 SSH (22) + Tailscale (41641/udp)
2. VPN (Tailscale) -- Gateway 网关只能通过 VPN mesh 访问
3. Docker 隔离 -- DOCKER-USER iptables 链防止外部端口暴露
4. Systemd 加固 -- NoNewPrivileges、PrivateTmp、非特权用户

验证你的外部攻击面：

nmap -p- YOUR_SERVER_IP

只有端口 22 (SSH) 应该处于开放状态。所有其他服务（Gateway 网关、Docker）都会被锁定。

Docker 是为智能体沙箱（隔离的工具执行）而安装的，不用于运行 Gateway 网关本身。沙箱配置请参阅 Multi-Agent Sandbox and Tools。

手动安装

如果你希望手动控制自动化流程：

bash
sudo apt update && sudo apt install -y ansible git


bash
git clone https://github.com/openclaw/openclaw-ansible.git
cd openclaw-ansible


bash
ansible-galaxy collection install -r requirements.yml


bash
./run-playbook.sh

或者，直接运行，然后在之后手动执行设置脚本：
```bash
ansible-playbook playbook.yml --ask-become-pass
# Then run: /tmp/openclaw-setup.sh
```

更新

Ansible 安装器会设置 OpenClaw 以便手动更新。标准更新流程请参阅 Updating。

重新运行 Ansible playbook（例如用于配置变更）：

cd openclaw-ansible
./run-playbook.sh

它是幂等的，可以安全地多次运行。

故障排除

- 确保你可以先通过 Tailscale VPN 访问
- SSH 访问（端口 22）始终允许
- Gateway 网关按设计只能通过 Tailscale 访问

```bash
# Check logs
sudo journalctl -u openclaw -n 100

# Verify permissions
sudo ls -la /opt/openclaw

# Test manual start
sudo -i -u openclaw
cd ~/openclaw
openclaw gateway run
```

```bash
# Verify Docker is running
sudo systemctl status docker

# Check sandbox image
sudo docker images | grep openclaw-sandbox

# Build sandbox image if missing (requires source checkout)
cd /opt/openclaw/openclaw
sudo -u openclaw ./scripts/sandbox-setup.sh
# For npm installs without a source checkout, see
# https://docs.openclaw.ai/gateway/sandboxing#images-and-setup
```

确保你正以 openclaw 用户运行：
bash
sudo -i -u openclaw
openclaw channels login

高级配置

有关详细的安全架构和故障排除，请参阅 openclaw-ansible 仓库：

• 安全架构
• 技术细节
• 故障排除指南

相关内容

• openclaw-ansible -- 完整部署指南
• Docker -- 容器化 Gateway 网关设置
• 沙箱隔离 -- 智能体沙箱配置
• Multi-Agent Sandbox and Tools -- 每个智能体的隔离

📄 Bun（实验性）

原文：https://docs.openclaw.ai/zh-CN/install/bun

Bun 不建议用于 Gateway 网关运行时（WhatsApp 和 Telegram 存在已知问题）。生产环境请使用 Node。

Bun 是可选的本地运行时，可用于直接运行 TypeScript（bun run ...、bun --watch ...）。默认包管理器仍然是 pnpm，它受到完全支持，并被文档工具使用。Bun 无法使用 pnpm-lock.yaml，并会忽略它。

安装

sh
bun install

`bun.lock` / `bun.lockb` 已加入 gitignore，因此不会造成仓库变更。要完全跳过 lockfile 写入：

```sh
bun install --no-save
```

sh
bun run build
bun run vitest run

生命周期脚本

Bun 会阻止依赖的生命周期脚本，除非显式信任。对于此仓库，常见被阻止的脚本并不是必需的：

• baileys preinstall -- 检查 Node 主版本 >= 20（OpenClaw 默认使用 Node 24，并且仍支持 Node 22 LTS，目前为 22.16+）
• protobufjs postinstall -- 输出关于不兼容版本方案的警告（无构建产物）

如果遇到需要这些脚本的运行时问题，请显式信任它们：

bun pm trust baileys protobufjs

注意事项

有些脚本目前仍硬编码 pnpm（例如 docs:build、ui:*、protocol:check）。暂时请通过 pnpm 运行这些脚本。

相关

• 安装概览
• Node.js
• 更新