ZeroClaw 云服务器部署指南

本文档记录了在 Linux 云服务器上从源代码构建 ZeroClaw、配置 Gateway、开放防火墙端口，以及解决 Web 仪表板缺失问题的完整过程。

1. 环境准备

• 操作系统：Ubuntu 24.04

2. 克隆 ZeroClaw 源代码

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw

3. 安装

./install.sh

安装完成后，按照提示选择 AI 提供商、输入 API Key、选择模型等。完成向导后会自动生成配置文件 ~/.zeroclaw/config.toml。

4. 修改 Gateway 配置

编辑配置文件：

vim ~/.zeroclaw/config.toml

在 [gateway] 部分添加或修改以下内容：

[gateway]
host = "0.0.0.0"
port = 42617
allow_public_bind = true   # 必须设置为 true 才能绑定到公网地址

5. 开放防火墙端口

5.1 云服务商安全组

在云服务商控制台的安全组中放行 42617 端口，来源 IP 可根据需要设置为 0.0.0.0/0（所有来源）或指定 IP 范围。

5.2 操作系统防火墙（UFW）

sudo ufw allow 42617/tcp
sudo ufw reload

6. 启动 Gateway 并解决 "Web dashboard not available"

6.1 构建前端静态文件

进入源码目录下的 web 文件夹，安装依赖并构建：

cd /root/zeroclaw/web
npm install
npm run build

构建完成后，前端静态文件会输出到 web/dist 目录。

6.2 配置前端静态文件路径

编辑 ~/.zeroclaw/config.toml，在 [gateway] 部分添加：

web_dist_dir = "/root/zeroclaw/web/dist"   # 替换为你的实际绝对路径

6.3 添加环境变量（防止 PATH 问题）

export PATH="$HOME/.cargo/bin:$PATH"

7. 启动 ZeroClaw Gateway

前台启动

zeroclaw gateway start

后台运行（推荐）

nohup zeroclaw gateway start > gateway.log 2>&1 &

常见问题

Q: 启动时报错 Error: Address already in use

A：说明端口被占用。执行以下命令找到占用进程并终止：

lsof -i :42617
kill -9 <进程ID>

然后重新启动 Gateway。

Q: 浏览器无法访问

A：请依次检查：

1. 云服务商安全组是否放行了 42617 端口
2. 系统防火墙（UFW）是否放行了 42617 端口
3. Gateway 是否绑定了 0.0.0.0（而非 127.0.0.1）
4. 配置中 allow_public_bind = true 是否已设置

Q: 前端构建失败（npm ci 报错）

A：改用 npm install 代替 npm ci，然后执行 npm run build。

参考

• ZeroClaw 官方文档