[← 第 01 章](/openclaw-tutorial/01-%E5%9F%BA%E7%A1%80%E4%BB%8B%E7%BB%8D%E4%B8%8E%E5%AE%89%E8%A3%85.html) · [📑 目录](/openclaw-tutorial/) · [📋 大纲](/openclaw-tutorial/OUTLINE.html) · [第 03 章 →](/openclaw-tutorial/03-Skills%20%E6%8F%92%E4%BB%B6%E4%BD%93%E7%B3%BB%E4%B8%8E%E6%89%B9%E9%87%8F%E5%BC%80%E5%8F%91.html)

第 2 章：部署与环境初始化

难度: ⭐ 入门 预计阅读: 15 分钟 前置章节: 第 1 章

📑 本章目录

2.1 部署模式概览
2.2 Gateway 服务管理
2.3 OpenClaw.json 核心配置
2.4 systemd 服务配置（Linux）
2.5 Docker 部署
2.6 初始化向导
2.7 环境变量配置
2.8 健康检查与诊断
2.9 常见部署问题
2.10 云平台部署指南
常见问题 (FAQ)
Q2：Gateway 启动后端口被占用怎么办？
Q3：Docker 部署时容器无法访问宿主机网络怎么办？
Q4：如何在不重启服务的情况下重新加载配置？
Q5：systemd 服务设置了 enable 但重启后没有自启动？
实操练习
练习 2：使用 Docker Compose 部署并验证
练习 3：自定义配置并切换端口
外部参考链接
本章小结

本章详细介绍 OpenClaw 的多种部署方式与环境初始化配置，帮助用户完成生产级或开发环境搭建。

2.1 部署模式概览

OpenClaw 支持多种部署模式，你可以根据团队规模、安全要求和基础设施条件选择最合适的方式。单机部署适合个人开发和测试；Docker 容器部署便于在云服务器上快速拉起服务且可跨平台迁移；多 Agent 部署适合需要角色隔离的团队；分布式集群适合高可用的企业级场景。下表对比了各模式的特点：

模式	说明	适用场景
本地单机部署	Gateway + Agent 运行在同一主机	个人开发、单用户
多 Agent 部署	单 Gateway 下配置多个 Agent	多项目隔离、多角色协作
Docker 容器部署	容器化运行，便于迁移和扩展	云服务器、CI/CD 环境
分布式部署	多 Gateway + 多 Agent 集群	高可用、多团队协作

2.2 Gateway 服务管理

Gateway 是 OpenClaw 的核心网关服务，负责消息路由、Agent 调度和权限管理。所有来自飞书、浏览器或 CLI 的请求都需经过 Gateway 转发到对应的 Agent。Gateway 以守护进程方式运行，支持自动重启和平滑升级。默认监听端口为 18789，可通过 --port 参数或 openclaw.json 中的 gateway.port 字段修改。

安装 Gateway 服务

openclaw daemon install --port 18789 --token <your-token>

服务管理命令

openclaw daemon status   # 查看 Gateway 服务状态
openclaw daemon start    # 启动 Gateway 服务
openclaw daemon stop     # 停止 Gateway 服务
openclaw daemon restart  # 重启 Gateway 服务
openclaw daemon uninstall # 卸载 Gateway 服务

直接启动 Gateway（调试用）

openclaw gateway start --host 0.0.0.0 --port 18789
openclaw gateway status

2.3 OpenClaw.json 核心配置

配置文件位于 ~/.openclaw/openclaw.json，核心配置项包括：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "<your-gateway-token>"
    }
  },
  "channels": {
    "feishu": {
      "appId": "<feishu-app-id>",
      "appSecret": "<feishu-app-secret>",
      "enabled": true,
      "connectionMode": "websocket"
    }
  },
  "skills": {

    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "<tavily-api-key>"
      }
    }
  },
  "plugins": {
    "entries": {
      "feishu": { "enabled": true }
    }
  }
}

常用配置说明

配置项	说明
`gateway.port`	Gateway 监听端口，默认 18789
`gateway.bind`	绑定地址，loopback 仅本地访问
`gateway.auth.token`	Gateway 访问令牌
`channels.*`	消息渠道配置（飞书、Slack 等）
`skills.entries.*`	技能配置与 API Key
`plugins.entries.*`	插件启用配置

2.4 systemd 服务配置（Linux）

OpenClaw 在 Linux 上使用 systemd 管理 Gateway 服务。openclaw daemon install 会自动创建用户级 service 文件，支持开机自启、自动重启和日志收集。如果你需要修改服务行为（如增大内存限制或修改重启策略），可以直接编辑该 service 文件后执行 systemctl --user daemon-reload。

服务文件位置

~/.config/systemd/user/openclaw-gateway.service

以下是 openclaw daemon install 自动生成的服务文件示例，了解其内容有助于自定义调优：

[Unit]
Description=OpenClaw Gateway Service
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
ExecStart=/usr/bin/env node /usr/lib/node_modules/openclaw/dist/gateway.js --port 18789
Restart=on-failure
RestartSec=10
Environment=NODE_ENV=production
Environment=OPENCLAW_DATA_DIR=%h/.openclaw
WorkingDirectory=%h/.openclaw
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=default.target

[!TIP] 如果需要增大 Node.js 内存限制（默认约 1.5 GB），可在 ExecStart 行的 node 后添加 --max-old-space-size=4096 参数。修改 service 文件后必须执行 systemctl --user daemon-reload 重新加载配置，否则更改不会生效。

手动管理服务

systemctl --user status openclaw-gateway
systemctl --user start openclaw-gateway
systemctl --user stop openclaw-gateway
systemctl --user restart openclaw-gateway
systemctl --user enable openclaw-gateway  # 开机自启

查看服务日志

journalctl --user -u openclaw-gateway -f

2.5 Docker 部署

Docker 部署适合需要环境隔离、快速迁移或在 CI/CD 流水线中运行 OpenClaw 的场景。官方镜像已包含 Node.js 和所有运行时依赖，只需挂载配置目录即可。注意容器内默认端口为 18789，需要映射到宿主机。

使用官方镜像

docker pull openclaw/openclaw:latest
docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

docker-compose 示例

version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped

启动：

docker-compose up -d

2.6 初始化向导

首次安装后推荐运行初始化向导，它以交互式问答的方式引导你完成全部基础配置。向导是幂等的——重复运行不会覆盖已有配置，只会补充缺失项。

openclaw onboard --install-daemon

向导流程详解

步骤	操作内容	产物
1. 环境检测	校验 Node.js、npm、git 版本，检查磁盘空间	输出检测报告
2. Gateway 配置	设置监听端口、生成访问 Token、选择绑定地址	写入 `openclaw.json` 的 `gateway` 段
3. AI 提供商	选择 OpenAI / Anthropic / Azure 等，填入 API Key	写入 `openclaw.json` 的 `ai` 段
4. 消息渠道	配置飞书 / Slack / Discord 连接凭证	写入 `openclaw.json` 的 `channels` 段
5. 推荐技能	安装 tavily（搜索）、file-manager 等常用技能	技能文件写入 `~/.openclaw/skills/`
6. 守护进程	注册 systemd 服务并启动 Gateway	生成 service 文件并 enable
7. 健康检查	运行 `openclaw doctor` 并验证端到端连通性	输出最终状态报告

向导执行过程中会在终端显示每一步的操作结果（绿色 ✔ 表示通过，红色 ✘ 表示失败）。如果某步失败，向导会提示修复建议并允许你重试该步骤。

跳过特定步骤

# 跳过消息渠道和技能安装（适合纯 CLI 使用场景）
openclaw onboard --skip-channels --skip-skills

# 完全非交互模式（适合 CI/CD 或脚本化部署）
openclaw onboard --install-daemon --yes --skip-channels

[!TIP] 如果你在一台已有旧版 OpenClaw 配置的机器上重新运行向导，它会检测已有配置并提示是否保留。建议在升级前先备份 ~/.openclaw/openclaw.json，以便出现问题时快速回滚。

2.7 环境变量配置

除 openclaw.json 外，也支持通过环境变量覆盖配置。环境变量优先级高于配置文件，适合 CI/CD 和容器化场景。

export OPENCLAW_GATEWAY_PORT=18789
export OPENCLAW_GATEWAY_TOKEN=<your-token>
export OPENAI_API_KEY=<your-openai-key>
export ANTHROPIC_API_KEY=<your-claude-key>

环境变量说明

环境变量	说明	默认值
`OPENCLAW_GATEWAY_PORT`	Gateway 监听端口	`18789`
`OPENCLAW_GATEWAY_TOKEN`	Gateway 访问认证令牌	无（必须设置）
`OPENAI_API_KEY`	OpenAI API 密钥，用于 GPT 模型调用	无
`ANTHROPIC_API_KEY`	Anthropic API 密钥，用于 Claude 模型调用	无
`OPENCLAW_LOG_LEVEL`	日志级别（debug/info/warn/error）	`info`
`OPENCLAW_DATA_DIR`	OpenClaw 数据目录	`~/.openclaw`

持久化环境变量

将环境变量写入 Shell 配置文件以实现持久化：

# 写入 ~/.bashrc（Bash 用户）
echo 'export OPENCLAW_GATEWAY_PORT=18789' >> ~/.bashrc
source ~/.bashrc

# 写入 ~/.zshrc（Zsh 用户）
echo 'export OPENCLAW_GATEWAY_PORT=18789' >> ~/.zshrc
source ~/.zshrc

[!TIP] 敏感信息（如 API Key、Token）建议使用 .env 文件或密钥管理工具，避免直接写入 Shell 配置。

2.8 健康检查与诊断

系统诊断

openclaw doctor        # 全面检测依赖、配置、服务状态
openclaw doctor --fix  # 自动修复可修复的问题

服务状态

openclaw status        # 查看主服务状态
openclaw gateway status --deep  # 深度检测 Gateway

日志查看

openclaw logs --follow  # 实时查看 Gateway 日志

2.9 常见部署问题

问题	解决方法
端口被占用	修改 `gateway.port` 或释放占用端口
服务无法启动	运行 `openclaw doctor` 检测原因
Token 不匹配	确认 OpenClaw.json 和服务配置一致
无法访问 Gateway	检查防火墙和 `gateway.bind` 配置
systemd 服务异常	运行 `openclaw daemon install --force` 重装

端口被占用的排查与修复

当 Gateway 启动失败并报 EADDRINUSE 错误时，说明目标端口已被其他进程占用。排查步骤：

# 查找占用端口 18789 的进程
lsof -i :18789
# 或使用 ss 命令
ss -tlnp | grep 18789

# 方案 A：终止占用进程（确认进程可停止后）
kill -9 <PID>

# 方案 B：更换 Gateway 端口
openclaw config set gateway.port 18790
openclaw daemon restart

Token 不匹配排查

Token 不匹配通常发生在手动编辑配置文件后忘记重启服务，或在 openclaw daemon install 时使用了与配置文件不同的 Token。排查方法：

# 查看配置文件中的 Token
jq '.gateway.auth.token' ~/.openclaw/openclaw.json

# 查看正在运行的服务使用的 Token（从进程参数中获取）
ps aux | grep openclaw-gateway

# 统一 Token 后重启
openclaw daemon install --port 18789 --token <正确的Token> --force

[!TIP] 部署过程中遇到无法自行解决的问题，可运行 openclaw doctor --export 生成诊断报告文件，将其发送到社区 Discord 或 GitHub Issues 以获取帮助。报告会自动脱敏 API Key 等敏感信息。

2.10 云平台部署指南

OpenClaw 支持主流云平台部署，包括 Azure、DigitalOcean、腾讯云等。云平台部署时需注意以下要点：

云平台	推荐方式	注意事项
Azure VM	Windows/Linux 虚拟机直装	需开放 18789 端口并配置 NSG 规则
DigitalOcean	Droplet + Docker	推荐使用 1-Click 应用或手动 Docker 部署
腾讯云 / 阿里云	轻量服务器 + systemd	配置安全组放行对应端口
自建服务器	裸金属 + systemd	适合内网环境，性能最优

云平台部署通用流程

# 1. 安装 Node.js（要求 >= 20，推荐 v22）
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

# 2. 安装 OpenClaw
npm install -g @anthropic-ai/openclaw

# 3. 初始化并启动（非交互模式，适合无人值守部署）
openclaw onboard --install-daemon --yes

# 4. 配置外部访问
openclaw config set gateway.bind 0.0.0.0

# 5. 验证服务
openclaw doctor
openclaw status

部署到云服务器后，还需要配置防火墙和安全组规则以放行 Gateway 端口：

# Ubuntu/Debian — 使用 ufw 放行端口
sudo ufw allow 18789/tcp
sudo ufw reload

# CentOS/RHEL — 使用 firewalld
sudo firewall-cmd --permanent --add-port=18789/tcp
sudo firewall-cmd --reload

[!NOTE] 云服务器上运行 OpenClaw 时，务必将 gateway.bind 设置为 0.0.0.0 以允许外部访问，并配置防火墙/安全组规则。

[!TIP] 生产环境建议在 Gateway 前部署反向代理（如 Nginx）并启用 HTTPS，避免 API Token 以明文在公网传输。Nginx 配置示例：proxy_pass http://127.0.0.1:18789;，同时将 gateway.bind 保持为 loopback 以增强安全性。

常见问题 (FAQ)

Q1：安装 OpenClaw 后运行 `openclaw` 提示 “command not found”？

A：通常是 npm 全局安装路径未加入 PATH。执行以下命令检查和修复：

# 查看 npm 全局安装路径
npm config get prefix

# 将路径加入 PATH（以 /usr/local 为例）
export PATH="$(npm config get prefix)/bin:$PATH"
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc

Q2：Gateway 启动后端口被占用怎么办？

A：端口冲突是部署中常见问题，可按以下步骤排查并解决：

# 步骤 1：查看端口占用情况（确认是哪个进程占用）
lsof -i :18789
# 或使用 ss 命令
ss -tlnp | grep 18789

# 步骤 2（方法一）：释放被占用的端口
kill -9 <PID>

# 步骤 2（方法二）：更换为其他可用端口
openclaw daemon install --port 18790 --token <your-token>

如果更换了端口，还需要检查防火墙规则是否放行了新端口：

# Ubuntu/Debian（ufw）
sudo ufw allow 18790/tcp
sudo ufw status

# CentOS/RHEL（firewalld）
sudo firewall-cmd --permanent --add-port=18790/tcp
sudo firewall-cmd --reload

# 云服务器还需在安全组中放行对应端口

💡 提示：如果反复出现端口冲突，可能是之前的 OpenClaw 进程未正确退出。使用 pgrep -f openclaw-gateway 检查残留进程，确保全部终止后再重新启动。

Q3：Docker 部署时容器无法访问宿主机网络怎么办？

A：容器默认使用 bridge 网络，可能无法直接访问宿主机服务。以下是几种解决方案：

方案一：使用 --network host 模式（最简单）

# 容器直接共享宿主机网络栈，无需端口映射
docker run -d --name openclaw --network host \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

方案二：docker-compose 中使用 network_mode

# docker-compose.yml
services:
  openclaw:
    image: openclaw/openclaw:latest
    network_mode: host
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped

方案三：使用 host.docker.internal 访问宿主机（macOS/Windows）

如果不能使用 host 模式，可在配置中将宿主机地址替换为 host.docker.internal。Linux 用户需手动添加：

docker run -d --name openclaw \
  --add-host=host.docker.internal:host-gateway \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  openclaw/openclaw:latest

如果容器内出现 DNS 解析失败的问题，可在 docker-compose 中显式指定 DNS 服务器：

services:
  openclaw:
    dns:
      - 8.8.8.8
      - 114.114.114.114

💡 提示：使用 docker exec -it openclaw ping host.docker.internal 可快速测试容器到宿主机的连通性。

Q4：如何在不重启服务的情况下重新加载配置？

A：OpenClaw 支持多种方式热重载配置，无需完全重启服务即可使更改生效：

方法一：使用 daemon restart（推荐，平滑重启）

# 平滑重启，会先加载新配置再切换，尽量减少服务中断
openclaw daemon restart

方法二：发送 SIGHUP 信号（零停机重载）

# 向 Gateway 进程发送 SIGHUP 信号触发配置重载
kill -HUP $(pgrep -f openclaw-gateway)

此方式不会中断现有连接，Gateway 会在后台重新读取 openclaw.json 并应用新配置。

方法三：使用 OpenClaw config 命令修改（自动生效）

# 通过 CLI 修改配置项会自动触发热重载
openclaw config set gateway.port 18790
openclaw config set gateway.bind 0.0.0.0

验证配置是否已重载：

# 查看当前运行中的配置
openclaw doctor
# 检查日志确认重载成功
tail -5 ~/.openclaw/logs/config-audit.jsonl

⚠️ 注意：部分配置项（如端口变更）可能仍需完全重启才能生效。查看日志中是否有 config reloaded 确认重载成功。

Q5：systemd 服务设置了 enable 但重启后没有自启动？

A：用户级 systemd 服务在无用户登录的情况下默认不会启动，需按以下步骤排查并修复：

步骤 1：启用 lingering（核心原因）

# 启用 lingering，允许用户级服务在无登录会话时运行
sudo loginctl enable-linger $(whoami)

# 验证 lingering 状态
loginctl show-user $(whoami) | grep Linger
# 应输出：Linger=yes

步骤 2：确认服务已正确 enable

systemctl --user is-enabled openclaw-gateway
# 应输出：enabled

# 如果输出 disabled，重新启用
systemctl --user enable openclaw-gateway

步骤 3：检查服务依赖与目标

# 确认服务挂载到 default.target
systemctl --user list-dependencies default.target | grep openclaw

# 查看服务文件中的 WantedBy 是否正确
cat ~/.config/systemd/user/openclaw-gateway.service | grep WantedBy
# 应包含：WantedBy=default.target

步骤 4：查看启动失败日志

# 查看服务最近的日志，确认是否有启动错误
journalctl --user -u openclaw-gateway --no-pager -n 20

# 如果修改了服务文件，记得重载
systemctl --user daemon-reload
systemctl --user restart openclaw-gateway

💡 提示：如果使用的是系统级服务（非用户级），则需要 sudo systemctl enable openclaw-gateway，并确保服务文件位于 /etc/systemd/system/ 目录下。

进阶：部署架构深入

理解部署架构有助于根据不同环境选择最佳部署方案：

单机部署 vs 分布式部署：小团队推荐单机部署（Gateway + Agent 同进程），大规模场景可将 Gateway 与 Agent 分离部署，通过 HTTP/WebSocket 通信。
容器化编排：使用 Docker Compose 管理多组件部署时，建议将配置文件通过 volume 挂载而非 COPY 进镜像，便于运行时修改。
环境变量优先级：OpenClaw 配置加载顺序为环境变量 > openclaw.json > 默认值，生产环境建议敏感配置（API Key 等）通过环境变量注入。
健康检查机制：Gateway 内置 /health 端点，容器编排工具应配置 liveness 和 readiness 探针，间隔建议 30 秒。
日志持久化：生产环境务必将 ~/.openclaw/logs/ 目录挂载到持久存储，便于故障回溯和审计。

注意事项与常见错误

部署过程中最常见的错误及对应的排查思路：

常见错误	症状	解决方案
端口冲突	Gateway 启动失败，报 `EADDRINUSE`	使用 `lsof -i :端口号` 检查占用进程
配置文件路径错误	启动后行为异常，使用默认配置	确认 `OPENCLAW_HOME` 环境变量指向正确目录
Docker 网络隔离	容器内无法访问宿主机服务	使用 `host.docker.internal` 或 `--network host`
systemd 服务不启动	`enable` 后重启无效	检查 `ExecStart` 路径是否正确，运行 `journalctl -u openclaw-gateway` 查看日志

⚠️ 注意：切勿在生产环境使用 openclaw gateway start 前台模式运行，应始终通过 systemd 或 Docker 管理进程生命周期。

进阶：部署架构与容器化原理

生产环境部署时，理解 OpenClaw 的服务架构有助于选择最优部署方案：

部署模式	适用场景	优势	复杂度
单机直装	个人开发	简单快速	⭐
systemd 服务	服务器常驻	自动重启、日志管理	⭐⭐
Docker 容器	团队/CI	环境隔离、可复制	⭐⭐⭐
K8s 编排	企业规模	弹性伸缩、高可用	⭐⭐⭐⭐

注意事项与常见错误

部署过程中以下错误最为常见：

常见错误	后果	正确做法
未配置持久化存储	容器重启后数据丢失	挂载 `~/.openclaw` 到宿主机卷
端口冲突未检查	Gateway 启动失败	部署前 `lsof -i :18789` 检查
环境变量未传入容器	API Key 等配置丢失	使用 `--env-file` 或 K8s Secret

进阶：部署架构与容器化原理

生产环境部署时的架构选型：

部署模式	适用场景	优势	复杂度
单机直装	个人开发	简单快速	⭐
systemd 服务	服务器常驻	自动重启	⭐⭐
Docker 容器	团队/CI	环境隔离	⭐⭐⭐
K8s 编排	企业规模	弹性伸缩	⭐⭐⭐⭐

注意事项与常见错误

部署常见错误：

常见错误	后果	正确做法
未配置持久化存储	数据丢失	挂载宿主机卷
端口冲突	启动失败	部署前检查端口
环境变量未传入	配置丢失	使用 env-file

实操练习

练习 1：从零部署 OpenClaw 并完成健康检查

目标：完成 OpenClaw 的安装、初始化与验证。

# 步骤 1：安装 OpenClaw
npm install -g @anthropic-ai/openclaw

# 步骤 2：运行初始化向导
openclaw onboard --install-daemon

# 步骤 3：验证安装
openclaw --version
openclaw status

# 步骤 4：运行系统诊断
openclaw doctor

验收标准：openclaw doctor 全部通过，openclaw status 显示 Gateway 运行中。

练习 2：使用 Docker Compose 部署并验证

目标：通过 Docker Compose 启动 OpenClaw 并确认服务可用。

# 步骤 1：创建项目目录
mkdir -p ~/openclaw-docker && cd ~/openclaw-docker

# 步骤 2：创建 docker-compose.yml
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    ports:
      - "18789:18789"
    volumes:
      - ~/.openclaw:/root/.openclaw
    restart: unless-stopped
EOF

# 步骤 3：启动服务
docker-compose up -d

# 步骤 4：验证服务
docker logs openclaw
curl -s http://localhost:18789/health

验收标准：curl 返回健康状态，容器日志无报错。

练习 3：自定义配置并切换端口

目标：修改 Gateway 端口并验证配置生效。

# 步骤 1：备份当前配置
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

# 步骤 2：修改端口（将 18789 改为 19000）
openclaw config set gateway.port 19000

# 步骤 3：重启服务
openclaw daemon restart

# 步骤 4：验证新端口
openclaw status
curl -s http://localhost:19000/health

# 步骤 5：恢复原端口
openclaw config set gateway.port 18789
openclaw daemon restart

验收标准：端口切换后服务正常运行，切换回来后同样正常。

外部参考链接

OpenClaw 官方文档 - Getting Started — 快速上手与首次配置
OpenClaw Gateway 远程部署完整指南 — Linux 无头服务器部署详解
Azure VM 部署 OpenClaw 完整指南 — Windows/Azure 环境部署
DigitalOcean 部署 OpenClaw 教程 — Droplet 手动部署与 1-Click 部署
systemd 服务管理手册 — systemd 命令参考
Docker Compose 官方文档 — 容器编排配置参考

参考来源

来源	链接	可信度	说明
OpenClaw 官方文档	https://docs.OpenClaw.ai	A	安装, 配置, 命令
OpenClaw GitHub 仓库	https://github.com/OpenClaw/OpenClaw	A	源码, Issues, Release
ClawHub Skills 平台	https://hub.OpenClaw.ai	A	Skills, 市场, 安装
Docker 官方文档	https://docs.docker.com	A	Docker, 容器, 部署
systemd 管理文档	https://www.freedesktop.org/wiki/Software/systemd/	A	systemd, 服务管理, 后台运行

Troubleshooting

本节汇总部署过程中遇到的典型故障及排查步骤。

Gateway 启动后立即退出

症状：openclaw daemon status 显示 inactive (dead) 或 failed。

排查步骤：

查看系统日志：journalctl --user -u openclaw-gateway --no-pager -n 50
检查端口占用：lsof -i :18789
验证配置文件 JSON 格式：python3 -m json.tool ~/.openclaw/openclaw.json
检查 Node.js 版本：node -v（需 v20+）

Docker 容器无法连接外部网络

症状：容器内 curl 或 AI API 调用超时。

解决：

# 使用 host 网络模式
docker run --network host -v ~/.openclaw:/root/.openclaw openclaw/openclaw:latest

或在 docker-compose 中添加 DNS 配置：

services:
  openclaw:
    dns:
      - 8.8.8.8
      - 114.114.114.114

systemd 服务 enable 后重启不自动启动

原因：用户级 systemd 服务需要 lingering 支持，否则在用户未登录时服务不会自动拉起。此外，服务文件配置错误或依赖缺失也可能导致此问题。

解决：

# 1. 启用 lingering
sudo loginctl enable-linger $USER

# 2. 重新启用服务
systemctl --user enable openclaw-gateway

# 3. 验证服务状态与依赖
systemctl --user status openclaw-gateway
systemctl --user is-enabled openclaw-gateway

# 4. 检查启动日志排查失败原因
journalctl --user -u openclaw-gateway -b --no-pager | tail -20

# 5. 如果日志显示依赖问题，检查 After= 和 WantedBy= 配置
systemctl --user cat openclaw-gateway

💡 如果以上步骤都确认无误但问题仍存在，可尝试 systemctl --user daemon-reload 后重新 enable，确保 systemd 加载了最新的服务文件。

本章小结

OpenClaw 支持本地单机、Docker 容器、分布式集群等多种部署模式，可按需选择。
Gateway 是核心网关服务，通过 openclaw daemon 系列命令管理生命周期。
主配置文件 ~/.openclaw/openclaw.json 控制端口、认证、渠道、技能等核心设置。
环境变量可覆盖配置文件，适合 CI/CD 和容器化场景。
首次安装推荐使用 openclaw onboard 交互式向导完成初始化。
openclaw doctor 提供全面的系统诊断与自动修复能力，是排查问题的首选工具。
云平台部署时需注意安全组/防火墙规则和 gateway.bind 配置。

[← 上一章：基础介绍与安装](/openclaw-tutorial/01-%E5%9F%BA%E7%A1%80%E4%BB%8B%E7%BB%8D%E4%B8%8E%E5%AE%89%E8%A3%85.html) · [📑 返回目录](/openclaw-tutorial/) · [下一章：Skills 插件体系与批量开发 →](/openclaw-tutorial/03-Skills%20%E6%8F%92%E4%BB%B6%E4%BD%93%E7%B3%BB%E4%B8%8E%E6%89%B9%E9%87%8F%E5%BC%80%E5%8F%91.html)

第 2 章：部署与环境初始化

📑 本章目录

2.1 部署模式概览

2.2 Gateway 服务管理

安装 Gateway 服务

服务管理命令

直接启动 Gateway（调试用）

2.3 OpenClaw.json 核心配置

常用配置说明

2.4 systemd 服务配置（Linux）

服务文件位置

手动管理服务

查看服务日志

2.5 Docker 部署

使用官方镜像

docker-compose 示例

2.6 初始化向导

向导流程详解

跳过特定步骤

2.7 环境变量配置

环境变量说明

持久化环境变量

2.8 健康检查与诊断

系统诊断

服务状态

日志查看

2.9 常见部署问题

端口被占用的排查与修复

Token 不匹配排查

2.10 云平台部署指南

云平台部署通用流程

常见问题 (FAQ)

Q1：安装 OpenClaw 后运行 openclaw 提示 “command not found”？

Q2：Gateway 启动后端口被占用怎么办？

Q3：Docker 部署时容器无法访问宿主机网络怎么办？

Q4：如何在不重启服务的情况下重新加载配置？

Q5：systemd 服务设置了 enable 但重启后没有自启动？

进阶：部署架构深入

注意事项与常见错误

进阶：部署架构与容器化原理

注意事项与常见错误

进阶：部署架构与容器化原理

注意事项与常见错误

实操练习

练习 1：从零部署 OpenClaw 并完成健康检查

练习 2：使用 Docker Compose 部署并验证

练习 3：自定义配置并切换端口

外部参考链接

参考来源

Troubleshooting

Gateway 启动后立即退出

Docker 容器无法连接外部网络

systemd 服务 enable 后重启不自动启动

本章小结

Q1：安装 OpenClaw 后运行 `openclaw` 提示 “command not found”？