GithubBackup/clawpanel
1
0
Fork 0
mirror of https://github.com/qingchencloud/clawpanel.git synced 2026-05-11 18:10:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: rewrite deploy docs to be about ClawPanel Web版 (not OpenClaw)

Browse Source 
ClawPanel is the management tool - the docs should be about deploying
ClawPanel itself on Linux/Docker, not OpenClaw Gateway.

- Rewrite linux-deploy.md: ClawPanel Web版 Linux deployment guide
- Rewrite docker-deploy.md: ClawPanel Web版 Docker deployment guide
- Rewrite linux-deploy.sh: one-click script deploys ClawPanel Web + OpenClaw
- Update README deploy sections with correct descriptions and commands
- Update index.html deploy section and docs center card descriptions
- Port changed from 18789 (Gateway) to 1420 (ClawPanel Web)
This commit is contained in:
晴天
2026-03-05 23:10:46 +08:00
parent 05c5876090
commit b709b70839
5 changed files with 571 additions and 1177 deletions
Download Patch File Download Diff File Expand all files Collapse all files

725
docs/docker-deploy.md
View File

@@ -1,665 +1,350 @@
# Docker 部署指南
# ClawPanel Docker 部署指南
使用 Docker 一键部署 OpenClaw Gateway，无需安装 Node.js，开箱即用。
本文介绍如何用 Docker 部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。
> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Docker 部署让你在任何有 Docker 的机器上一键跑起 ClawPanel Web 管理面板。
---
## 目录
- [快速开始](#快速开始)
- [Docker Compose 部署](#docker-compose-部署)
- [配置说明](#配置说明)
- [模型配置](#模型配置)
- [数据持久化](#数据持久化)
- [网络与端口](#网络与端口)
- [反向代理](#反向代理)
- [架构说明](#架构说明)
- [方式一：快速启动](#方式一快速启动)
- [方式二：Docker Compose（推荐）](#方式二docker-compose推荐)
- [方式三：自定义 Dockerfile](#方式三自定义-dockerfile)
- [配置与数据](#配置与数据)
- [连接 Gateway](#连接-gateway)
- [Nginx 反向代理](#nginx-反向代理)
- [常用命令](#常用命令)
- [升级](#升级)
- [更新升级](#更新升级)
- [常见问题](#常见问题)
---
## 快速开始
## 架构说明
**一条命令启动：**
```bash
docker run -d \
--name openclaw \
--restart unless-stopped \
-p 18789:18789 \
-v openclaw-data:/root/.openclaw \
node:22-slim \
sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && openclaw gateway start"
```
浏览器 ──HTTP──▶ ClawPanel Web 容器 (:1420)
│
├── /__api/* 读写 ~/.openclaw/ 配置
├── /ws WebSocket 代理 → Gateway
└── 管理 Gateway 进程
│
▼
OpenClaw Gateway (容器内或宿主机, :18789)
```
启动后访问 `http://你的服务器IP:18789`。
> ⚠️ 首次启动需要下载安装 OpenClaw，可能需要 1-2 分钟。后续重启会直接启动。
ClawPanel Web 版 = Vite 开发服务器 + `dev-api.js` 后端中间件，在容器内提供完整管理功能。
---
## Docker Compose 部署
## 方式一：快速启动
推荐使用 Docker Compose，配置更清晰，管理更方便。
### 1. 创建项目目录
最简单的方式，一条命令搞定：
```bash
mkdir -p ~/openclaw && cd ~/openclaw
docker run -d \
--name clawpanel \
--restart unless-stopped \
-p 1420:1420 \
-v clawpanel-data:/root/.openclaw \
node:22-slim \
sh -c "\
apt-get update && apt-get install -y git && \
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && \
openclaw init 2>/dev/null || true && \
git clone https://github.com/qingchencloud/clawpanel.git /app && \
cd /app && npm install && \
npx vite --port 1420 --host 0.0.0.0"
```
### 2. 创建配置文件
访问 `http://服务器IP:1420` 即可使用。
```bash
cat > openclaw.json << 'EOF'
{
"mode": "local",
"tools": {
"profile": "full",
"sessions": {
"visibility": "all"
}
},
"gateway": {
"port": 18789,
"bind": "lan",
"auth": {
"mode": "token",
"token": "your-secret-token-change-me"
}
},
"models": {
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-your-api-key",
"models": [
{ "id": "deepseek-chat", "name": "DeepSeek V3" },
{ "id": "deepseek-reasoner", "name": "DeepSeek R1" }
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "deepseek/deepseek-chat"
}
}
}
}
EOF
```
> ⚠️ 这种方式每次重建容器都要重新 clone + npm install，适合快速体验。生产环境推荐使用 Compose 或自定义镜像。
> 记得修改 `token` 和 `apiKey` 为你的实际值。
---
### 3. 创建 docker-compose.yml
## 方式二：Docker Compose（推荐）
```bash
cat > docker-compose.yml << 'EOF'
创建 `docker-compose.yml`：
```yaml
version: '3.8'
services:
openclaw:
clawpanel:
build:
context: .
dockerfile: Dockerfile.clawpanel
container_name: clawpanel
restart: unless-stopped
ports:
- "1420:1420"
volumes:
- openclaw-data:/root/.openclaw
environment:
- NODE_ENV=production
gateway:
image: node:22-slim
container_name: openclaw
container_name: openclaw-gateway
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ./openclaw.json:/root/.openclaw/openclaw.json
- openclaw-data:/root/.openclaw
command: >
sh -c "
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com 2>/dev/null;
openclaw gateway start
"
environment:
- NODE_ENV=production
sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com &&
openclaw init 2>/dev/null || true &&
openclaw gateway start --foreground"
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
interval: 30s
timeout: 10s
timeout: 5s
retries: 3
start_period: 60s
volumes:
openclaw-data:
EOF
```
### 4. 启动
同目录下创建 `Dockerfile.clawpanel`：
```dockerfile
FROM node:22-slim
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
WORKDIR /app
RUN git clone https://github.com/qingchencloud/clawpanel.git . && \
npm install
EXPOSE 1420
CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"]
```
启动：
```bash
docker compose up -d
```
### 5. 查看日志
```bash
docker compose logs -f
```
看到 `Gateway listening on http://0.0.0.0:18789` 就说明启动成功了。
这样 ClawPanel 和 Gateway 共享同一个 `openclaw-data` 卷，ClawPanel 可以直接管理 Gateway。
---
## 使用自定义 Dockerfile（推荐生产环境）
## 方式三：自定义 Dockerfile
上面的方式每次容器重建都要重新 `npm install`，生产环境建议构建自定义镜像：
如果只需要 ClawPanel Web（Gateway 在宿主机或其他地方运行）：
### Dockerfile
```bash
cat > Dockerfile << 'EOF'
```dockerfile
FROM node:22-slim
# 安装 OpenClaw
RUN npm install -g @qingchencloud/openclaw-zh \
--registry https://registry.npmmirror.com \
&& npm cache clean --force
RUN apt-get update && apt-get install -y git && rm -rf /var/lib/apt/lists/*
# 安装 curl 用于健康检查
RUN apt-get update && apt-get install -y --no-install-recommends curl \
&& rm -rf /var/lib/apt/lists/*
# 安装 OpenClaw CLI（ClawPanel 需要读写配置）
RUN npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
# 配置目录
RUN mkdir -p /root/.openclaw
VOLUME /root/.openclaw
WORKDIR /app
RUN git clone https://github.com/qingchencloud/clawpanel.git . && \
npm install
EXPOSE 18789
EXPOSE 1420
CMD ["openclaw", "gateway", "start"]
EOF
CMD ["npx", "vite", "--port", "1420", "--host", "0.0.0.0"]
```
### docker-compose.yml（使用自定义镜像）
构建并运行：
```bash
cat > docker-compose.yml << 'EOF'
version: '3.8'
services:
openclaw:
build: .
container_name: openclaw
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ./openclaw.json:/root/.openclaw/openclaw.json
- openclaw-data:/root/.openclaw
environment:
- NODE_ENV=production
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
volumes:
openclaw-data:
EOF
```
```bash
# 构建并启动
docker compose up -d --build
```
这样容器重启时直接启动 Gateway，无需重复安装。
---
## 配置说明
### 核心配置项
| 字段 | 说明 | 默认值 |
|------|------|--------|
| `mode` | 运行模式，必须设置 | `"local"` |
| `tools.profile` | Agent 工具权限 | `"full"` |
| `tools.sessions.visibility` | 会话可见性 | `"all"` |
| `gateway.port` | Gateway 监听端口 | `18789` |
| `gateway.bind` | 绑定范围 | `"lan"` |
| `gateway.auth.mode` | 认证方式 | `"token"` |
| `gateway.auth.token` | 访问密钥 | 无 |
### bind 选项
| 值 | 说明 |
|------|------|
| `"loopback"` | 仅容器内部访问（127.0.0.1），Docker 环境下**不要用这个** |
| `"lan"` | 所有网卡（0.0.0.0），Docker 环境**必须用这个** |
> ⚠️ Docker 容器内必须用 `"lan"`，否则端口映射无法工作。
---
## 模型配置
在 `openclaw.json` 的 `models.providers` 中添加服务商。以下是常见服务商示例：
### DeepSeek
```json
{
"models": {
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-xxxx",
"models": [
{ "id": "deepseek-chat", "name": "DeepSeek V3" },
{ "id": "deepseek-reasoner", "name": "DeepSeek R1" }
]
}
}
}
}
```
### OpenAI
```json
{
"openai": {
"baseUrl": "https://api.openai.com/v1",
"apiKey": "sk-xxxx",
"models": [
{ "id": "gpt-4o", "name": "GPT-4o" },
{ "id": "gpt-4o-mini", "name": "GPT-4o Mini" }
]
}
}
```
### Claude（通过兼容 API）
```json
{
"claude": {
"baseUrl": "https://your-claude-proxy.com/v1",
"apiKey": "sk-xxxx",
"models": [
{ "id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4" }
]
}
}
```
### Ollama（本地模型）
```json
{
"ollama": {
"baseUrl": "http://host.docker.internal:11434/v1",
"apiKey": "ollama",
"models": [
{ "id": "qwen2.5:14b", "name": "Qwen 2.5 14B" },
{ "id": "deepseek-r1:8b", "name": "DeepSeek R1 8B" }
]
}
}
```
> 注意 Ollama 在 Docker 里要用 `host.docker.internal` 访问宿主机，Linux 下需要加 `--add-host=host.docker.internal:host-gateway`。
### Ollama + Docker 特殊配置
如果 Ollama 也运行在同一台机器上：
```yaml
services:
openclaw:
# ... 其他配置 ...
extra_hosts:
- "host.docker.internal:host-gateway"
```
或者让 OpenClaw 和 Ollama 共享 Docker 网络：
```yaml
services:
openclaw:
# ... 其他配置 ...
network_mode: host # 直接使用宿主机网络，Ollama 用 localhost:11434
# 或者 Ollama 也在 Compose 里
ollama:
image: ollama/ollama
ports:
- "11434:11434"
volumes:
- ollama-data:/root/.ollama
docker build -t clawpanel .
docker run -d \
--name clawpanel \
--restart unless-stopped \
-p 1420:1420 \
-v ~/.openclaw:/root/.openclaw \
clawpanel
```
---
## 数据持久化
## 配置与数据
OpenClaw 的所有数据在 `/root/.openclaw` 目录：
### 数据目录
| 路径 | 内容 |
|------|------|
| `openclaw.json` | 全局配置 |
| `agents/` | Agent 数据 |
| `memories/` | 记忆文件 |
ClawPanel 的所有数据都存储在 `~/.openclaw/` 目录中：
| 文件/目录 | 说明 |
|-----------|------|
| `openclaw.json` | 主配置文件（模型、Gateway、Agent 设置） |
| `mcp.json` | MCP 服务器配置 |
| `logs/` | Gateway 日志 |
| `backups/` | 配置备份 |
| `agents/` | Agent 数据（记忆、工作区） |
| `devices/` | 设备配对信息 |
通过 Docker Volume 或 bind mount 持久化：
### 持久化
```yaml
# Docker Volume（推荐，Docker 自动管理）
volumes:
- openclaw-data:/root/.openclaw
# Bind mount（挂载本地目录，方便直接编辑）
volumes:
- ./data:/root/.openclaw
```
### 备份
使用 Docker Volume 或 Bind Mount 持久化数据：
```bash
# 备份整个数据目录
docker cp openclaw:/root/.openclaw ./openclaw-backup-$(date +%Y%m%d)
# Docker Volume（推荐）
-v clawpanel-data:/root/.openclaw
# 仅备份配置
docker cp openclaw:/root/.openclaw/openclaw.json ./openclaw.json.bak
# Bind Mount（方便直接查看文件）
-v ~/.openclaw:/root/.openclaw
```
### 初始配置
首次启动如果没有 `openclaw.json`，可以先在容器内初始化：
```bash
docker exec -it clawpanel openclaw init
```
或者将已有配置挂载进去。
---
## 网络与端口
## 连接 Gateway
### 修改端口
### 场景一：Gateway 在同一个 Compose 中
```yaml
# docker-compose.yml
ports:
- "8080:18789" # 宿主机 8080 → 容器 18789
使用上面的 Compose 配置，ClawPanel 和 Gateway 共享数据卷，ClawPanel 自动通过本地回环连接 Gateway。
### 场景二：Gateway 在宿主机
如果 Gateway 运行在宿主机（不在 Docker 中），ClawPanel 容器需要访问宿主机网络：
```bash
docker run -d \
--name clawpanel \
--network host \
-v ~/.openclaw:/root/.openclaw \
clawpanel
```
或者同时修改配置文件中的端口：
使用 `--network host` 后，容器共享宿主机网络，ClawPanel 可以直接连接 `127.0.0.1:18789`。
```json
{
"gateway": {
"port": 8080
}
}
```
### 场景三：Gateway 在远程服务器
```yaml
ports:
- "8080:8080"
```
### 使用 host 网络
```yaml
services:
openclaw:
network_mode: host
# 不需要 ports 映射，直接用宿主机端口
```
适用于需要直接访问宿主机服务（如 Ollama）的场景。
修改 `openclaw.json` 中的 Gateway 端口配置，或在 ClawPanel 面板中设置 Gateway 地址。
---
## 反向代理
## Nginx 反向代理
### Nginx + Docker Compose
```yaml
version: '3.8'
services:
openclaw:
build: .
container_name: openclaw
restart: unless-stopped
volumes:
- ./openclaw.json:/root/.openclaw/openclaw.json
- openclaw-data:/root/.openclaw
# 不暴露端口到外部，只在内部网络
nginx:
image: nginx:alpine
container_name: openclaw-nginx
restart: unless-stopped
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx.conf:/etc/nginx/conf.d/default.conf
- ./certs:/etc/nginx/certs
depends_on:
- openclaw
volumes:
openclaw-data:
```
**nginx.conf：**
如果希望用域名 + HTTPS 访问：
```nginx
server {
listen 80;
server_name ai.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl http2;
server_name ai.example.com;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
server_name panel.yourdomain.com;
location / {
proxy_pass http://openclaw:18789;
proxy_pass http://127.0.0.1:1420;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
}
}
```
> **重要：** 必须配置 WebSocket 升级头，否则 ClawPanel 无法通过 `/ws` 连接 Gateway。
---
## 常用命令
```bash
# 启动
docker compose up -d
# 停止
docker compose down
# 重启
docker compose restart
# 查看状态
docker ps | grep clawpanel
# 查看日志
docker compose logs -f
# 查看最近 100 行日志
docker compose logs --tail 100
docker logs -f clawpanel
# 进入容器
docker exec -it openclaw sh
# 查看容器状态
docker compose ps
# 重新构建并启动（修改了 Dockerfile 后）
docker compose up -d --build
```
---
## 升级
### 使用自定义 Dockerfile
```bash
cd ~/openclaw
# 重新构建镜像（会拉取最新版 OpenClaw）
docker compose build --no-cache
docker exec -it clawpanel bash
# 重启
docker compose up -d
```
docker restart clawpanel
### 使用 node 基础镜像（容器内升级）
```bash
# 进入容器
docker exec -it openclaw sh
# 升级
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
# 退出容器
exit
# 重启容器
docker restart openclaw
# 停止并删除
docker stop clawpanel && docker rm clawpanel
```
---
## 多实例部署
## 更新升级
在同一台机器运行多个 OpenClaw 实例（不同端口、不同配置）：
### 更新 ClawPanel
```yaml
version: '3.8'
```bash
docker exec -it clawpanel bash -c "cd /app && git pull origin main && npm install"
docker restart clawpanel
```
services:
openclaw-main:
build: .
container_name: openclaw-main
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ./config-main.json:/root/.openclaw/openclaw.json
- main-data:/root/.openclaw
### 使用 Compose 重建
openclaw-dev:
build: .
container_name: openclaw-dev
restart: unless-stopped
ports:
- "18790:18789"
volumes:
- ./config-dev.json:/root/.openclaw/openclaw.json
- dev-data:/root/.openclaw
```bash
docker compose build --no-cache clawpanel
docker compose up -d clawpanel
```
volumes:
main-data:
dev-data:
### 更新 OpenClaw
```bash
docker exec -it clawpanel npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com
```
---
## 常见问题
### 容器启动后无法访问
### Q: 容器启动后打开面板是空白？
1. 确认 `gateway.bind` 是 `"lan"`（不是 `"loopback"`）
2. 检查端口映射：`docker compose ps`
3. 检查容器日志：`docker compose logs`
4. 检查防火墙是否放行端口
检查容器日志：
### 首次启动很慢
首次启动需要 `npm install` 安装 OpenClaw，耗时 1-2 分钟。建议使用[自定义 Dockerfile](#使用自定义-dockerfile推荐生产环境) 方案，构建时安装，启动时直接运行。
### 容器重启后配置丢失
确保使用了 volume 持久化：
```yaml
volumes:
- openclaw-data:/root/.openclaw
```bash
docker logs clawpanel
```
或 bind mount 挂载本地目录。
确认看到 `VITE ready` 和 `[dev-api] 开发 API 已启动` 输出。
### 连接 Ollama 报错
### Q: 面板显示 "openclaw.json 不存在"？
Docker 容器内 `localhost` 是容器自己，不是宿主机。访问宿主机的 Ollama 需要：
在容器内初始化 OpenClaw：
```yaml
extra_hosts:
- "host.docker.internal:host-gateway"
```bash
docker exec -it clawpanel openclaw init
```
然后 baseUrl 填 `http://host.docker.internal:11434/v1`。
### Q: Gateway 按钮不工作（Docker 环境）？
### 内存占用
容器内管理 Gateway 进程需要特殊权限。推荐方案：
OpenClaw Gateway 本身约 50-100MB。如果同时运行 Ollama 等本地模型，建议 4GB+ 内存。
1. **Compose 模式**：Gateway 作为独立容器运行，用 `docker compose restart gateway` 管理
2. **Host 网络模式**：`--network host` 让 ClawPanel 直接管理宿主机进程
### 时区问题
### Q: 数据会丢失吗？
```yaml
services:
openclaw:
environment:
- TZ=Asia/Shanghai
```
只要正确配置了 Volume 挂载（`-v clawpanel-data:/root/.openclaw`），容器删除重建不会丢失数据。
---
### Q: 与桌面版有什么区别？
## 完整示例
生产就绪的 docker-compose.yml：
```yaml
version: '3.8'
services:
openclaw:
build: .
container_name: openclaw
restart: unless-stopped
ports:
- "18789:18789"
volumes:
- ./openclaw.json:/root/.openclaw/openclaw.json
- openclaw-data:/root/.openclaw
environment:
- NODE_ENV=production
- TZ=Asia/Shanghai
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:18789/health"]
interval: 30s
timeout: 10s
retries: 3
start_period: 30s
deploy:
resources:
limits:
memory: 512M
logging:
driver: json-file
options:
max-size: "10m"
max-file: "3"
volumes:
openclaw-data:
```
| 功能 | 桌面版 (Win/Mac) | Docker Web 版 |
|------|-----------------|---------------|
| 配置管理 | ✅ | ✅ |
| Gateway 管理 | ✅ | ⚠️ 需 host 网络或 Compose |
| 模型测试 | ✅ | ✅ |
| 日志查看 | ✅ | ✅ |
| 备份管理 | ✅ | ✅ |
| Agent 记忆 | ✅ | ✅ |
| ZIP 导出 | ✅ | ❌ |
| 系统托盘 | ✅ | ❌ |
| 自动更新 | ✅ | 手动重建镜像 |

28
docs/index.html
View File

@@ -727,7 +727,7 @@
<div class="container-sm" style="position:relative;z-index:10">
<div class="section-header">
<h2 class="reveal section-title">服务器 <span class="gradient-text">部署指南</span></h2>
<p class="reveal section-desc">不用桌面环境，在 Linux 服务器或 Docker 上一键部署 OpenClaw Gateway</p>
<p class="reveal section-desc">没有桌面环境？在 Linux 或 Docker 上部署 ClawPanel Web 版，浏览器即可管理 OpenClaw</p>
</div>
<div class="deploy-grid">
<!-- Linux -->
@@ -747,7 +747,7 @@
<span class="terminal-title mono">bash</span>
</div>
<div class="terminal-body mono" style="padding:16px 20px;font-size:13px">
<div class="t-comment"># 一键安装 Node.js + OpenClaw + systemd 自启</div>
<div class="t-comment"># 一键部署 ClawPanel Web + OpenClaw + systemd 自启</div>
<div class="t-cmd">curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash</div>
</div>
</div>
@@ -756,7 +756,7 @@
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20"/></svg>
完整教程
</a>
<span style="color:var(--text-muted);font-size:12px;line-height:32px">Node.js 安装 · 配置模型 · systemd/PM2 · Nginx 反代 · 防火墙</span>
<span style="color:var(--text-muted);font-size:12px;line-height:32px">Node.js · OpenClaw · systemd/PM2 · Nginx 反代 · 防火墙</span>
</div>
</div>
<!-- Docker -->
@@ -767,7 +767,7 @@
</div>
<div>
<h3 class="deploy-title">Docker 部署</h3>
<p class="deploy-desc">容器化隔离，支持 Compose 编排、Nginx 反代、Ollama 联动</p>
<p class="deploy-desc">容器化隔离，支持 Compose 编排、自定义镜像、Nginx 反代</p>
</div>
</div>
<div class="terminal" style="margin:0">
@@ -776,10 +776,10 @@
<span class="terminal-title mono">bash</span>
</div>
<div class="terminal-body mono" style="padding:16px 20px;font-size:13px">
<div class="t-comment"># 一条命令启动 Gateway</div>
<div class="t-cmd">docker run -d --name openclaw --restart unless-stopped \</div>
<div class="t-cmd" style="padding-left:1em">-p 18789:18789 -v openclaw-data:/root/.openclaw \</div>
<div class="t-cmd" style="padding-left:1em">node:22-slim sh -c "npm i -g @qingchencloud/openclaw-zh && openclaw gateway start"</div>
<div class="t-comment"># 一条命令启动 ClawPanel Web</div>
<div class="t-cmd">docker run -d --name clawpanel -p 1420:1420 \</div>
<div class="t-cmd" style="padding-left:1em">-v clawpanel-data:/root/.openclaw node:22-slim \</div>
<div class="t-cmd" style="padding-left:1em">sh -c "apt-get update && apt-get install -y git && ..."</div>
</div>
</div>
<div style="margin-top:16px;display:flex;gap:12px;flex-wrap:wrap">
@@ -787,14 +787,14 @@
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H20v20H6.5a2.5 2.5 0 0 1 0-5H20"/></svg>
完整教程
</a>
<span style="color:var(--text-muted);font-size:12px;line-height:32px">Compose · Dockerfile · 模型配置 · Ollama · 多实例</span>
<span style="color:var(--text-muted);font-size:12px;line-height:32px">Compose · Dockerfile · Gateway 联动 · Nginx 反代</span>
</div>
</div>
</div>
<div class="reveal" style="text-align:center;margin-top:32px">
<p style="color:var(--text-muted);font-size:14px">
<svg width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="display:inline;vertical-align:-2px;opacity:0.7"><circle cx="12" cy="12" r="10"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>
部署完成后，用 ClawPanel 连接 <code style="background:var(--surface);padding:2px 8px;border-radius:4px;font-size:13px">http://服务器IP:18789</code> 即可远程管理模型、Agent、日志等。手机端可用 ClawApp。
部署完成后，访问 <code style="background:var(--surface);padding:2px 8px;border-radius:4px;font-size:13px">http://服务器IP:1420</code> 即可通过浏览器管理 OpenClaw，功能与桌面版一致。
</p>
</div>
</div>
@@ -813,7 +813,7 @@
<div class="doc-icon" style="background:rgba(234,179,8,0.12);color:#eab308">🖥️</div>
<div>
<h3>Linux 部署指南</h3>
<p>从零开始在 Linux 服务器上部署 OpenClaw Gateway，一键脚本 + 手动安装两种方式</p>
<p>在 Linux 服务器上部署 ClawPanel Web 版，通过浏览器远程管理 OpenClaw</p>
<div class="doc-tags">
<span class="doc-tag">一键部署</span>
<span class="doc-tag">systemd</span>
@@ -826,12 +826,12 @@
<div class="doc-icon" style="background:rgba(34,211,238,0.12);color:#22d3ee">🐳</div>
<div>
<h3>Docker 部署指南</h3>
<p>容器化部署 OpenClaw，支持 Compose 编排、自定义镜像、Ollama 联动、多实例</p>
<p>用 Docker 部署 ClawPanel Web 版，支持 Compose 编排、自定义镜像、Gateway 联动</p>
<div class="doc-tags">
<span class="doc-tag">Docker Compose</span>
<span class="doc-tag">Dockerfile</span>
<span class="doc-tag">Ollama</span>
<span class="doc-tag">反向代理</span>
<span class="doc-tag">Gateway 联动</span>
<span class="doc-tag">Nginx 反代</span>
</div>
</div>
</div>

729
docs/linux-deploy.md
View File

@@ -1,638 +1,385 @@
# Linux 服务器部署指南
# ClawPanel Linux 部署指南
本文介绍如何在 Linux 服务器上部署 OpenClaw，从零到跑通只需 5 分钟。
本文介绍如何在 Linux 服务器上部署 **ClawPanel Web 版**，通过浏览器远程管理 OpenClaw。
适用场景：云服务器、NAS、家庭 HomeLab、无 GUI 的 Linux 主机。
> **ClawPanel** 有 Win/Mac 桌面客户端，但 Linux 没有桌面版。Web 版通过 Vite + Node.js 后端运行，功能与桌面版一致。
---
## 目录
- [一键部署](#一键部署)
- [分步安装](#分步安装)
- [配置模型](#配置模型)
- [启动 Gateway](#启动-gateway)
- [开机自启](#开机自启)
- [远程管理](#远程管理)
- [反向代理](#反向代理)
- [架构说明](#架构说明)
- [前提条件](#前提条件)
- [方式一：一键部署](#方式一一键部署)
- [方式二：手动部署](#方式二手动部署)
- [方式三：Docker 部署](#方式三docker-部署)
- [访问 ClawPanel](#访问-clawpanel)
- [进程守护](#进程守护)
- [Nginx 反向代理](#nginx-反向代理)
- [防火墙配置](#防火墙配置)
- [更新升级](#更新升级)
- [常见问题](#常见问题)
---
## 一键部署
## 架构说明
复制以下命令到终端，一键完成 Node.js + OpenClaw 安装、配置、启动：
```
浏览器 ──HTTP──▶ ClawPanel Web (Vite + dev-api 后端, :1420)
│
├── /__api/* 读写 ~/.openclaw/ 配置文件
├── /ws WebSocket 代理 → Gateway
└── 管理 Gateway 进程 (启动/停止/重启)
│
▼
OpenClaw Gateway (:18789)
```
**ClawPanel Web 版** = Vite 开发服务器 + `dev-api.js` 后端中间件，提供：
- 配置读写（`openclaw.json`、`mcp.json`）
- Gateway 服务管理（启动/停止/重启/状态检测）
- 设备配对、模型测试、日志查看、备份管理
- WebSocket 代理到 Gateway
---
## 前提条件
| 依赖 | 最低版本 | 说明 |
|------|----------|------|
| Node.js | 18+ | 推荐 22 LTS |
| npm | 随 Node.js | 包管理器 |
| Git | 任意 | 克隆仓库 |
| OpenClaw | 最新 | ClawPanel 管理的对象 |
---
## 方式一：一键部署
```bash
curl -fsSL https://raw.githubusercontent.com/qingchencloud/clawpanel/main/scripts/linux-deploy.sh | bash
```
> 脚本会自动检测系统环境，安装 Node.js（如未安装），安装 OpenClaw 汉化版，配置默认参数，启动 Gateway。
脚本自动完成：
1. 检测系统、安装 Node.js（如果缺少）
2. 安装 OpenClaw 汉化版（如果缺少）
3. 克隆 ClawPanel 仓库、安装依赖
4. 创建 systemd 服务、开机自启
5. 启动 ClawPanel Web，输出访问地址
不想用一键脚本？往下看分步安装。
部署完成后访问 `http://服务器IP:1420`。
---
## 分步安装
## 方式二：手动部署
### 1. 安装 Node.js
OpenClaw 需要 Node.js >= 18。选择适合你的安装方式：
**方式一：包管理器（推荐）**
**Ubuntu / Debian：**
```bash
# Ubuntu / Debian
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
# CentOS / RHEL / Fedora
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs
# Alpine
apk add nodejs npm
```
**方式二：nvm（多版本管理）**
**CentOS / RHEL / Fedora：**
```bash
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash -
sudo yum install -y nodejs
```
**Alpine：**
```bash
apk add nodejs npm git
```
验证安装：
```bash
node -v # 应显示 v18+ 版本号
npm -v # 应显示 npm 版本号
node -v # v22.x.x
npm -v # 10.x.x
```
### 2. 安装 OpenClaw
ClawPanel 是 OpenClaw 的管理工具，需要先安装 OpenClaw：
```bash
# 使用淘宝镜像源（国内服务器推荐）
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
# 或使用官方源
npm install -g @qingchencloud/openclaw-zh
```
验证安装：
初始化配置（首次）：
```bash
openclaw --version
openclaw init
```
### 3. 初始化配置
### 3. 克隆 ClawPanel
```bash
# 创建配置目录
mkdir -p ~/.openclaw
# 写入基础配置
cat > ~/.openclaw/openclaw.json << 'EOF'
{
"mode": "local",
"tools": {
"profile": "full",
"sessions": {
"visibility": "all"
}
},
"gateway": {
"port": 18789,
"bind": "lan",
"auth": {}
},
"models": {
"providers": {}
}
}
EOF
cd /opt
sudo git clone https://github.com/qingchencloud/clawpanel.git
sudo chown -R $(whoami) clawpanel
cd clawpanel
npm install
```
**配置说明：**
| 字段 | 值 | 说明 |
|------|------|------|
| `mode` | `"local"` | 运行模式，必须设置 |
| `tools.profile` | `"full"` | Agent 工具权限，`full` 为全部开启 |
| `gateway.port` | `18789` | Gateway 监听端口 |
| `gateway.bind` | `"lan"` | `"loopback"` 仅本机 / `"lan"` 局域网可访问 |
| `gateway.auth` | `{}` | 认证配置，生产环境建议设置 Token |
**设置访问密钥（推荐）：**
如果你的服务器有公网 IP 或局域网内有其他设备访问，强烈建议设置 Token：
### 4. 启动 ClawPanel Web
```bash
# 用 jq 修改（需安装 jq）
jq '.gateway.auth = {"mode": "token", "token": "你的密钥"}' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json
npx vite --port 1420 --host 0.0.0.0
```
# 或直接编辑
nano ~/.openclaw/openclaw.json
看到以下输出即为成功：
```
VITE v6.x.x ready in xxx ms
➜ Local: http://localhost:1420/
➜ Network: http://xxx.xxx.xxx.xxx:1420/
[dev-api] 开发 API 已启动，配置目录: /root/.openclaw
```
打开浏览器访问 `http://服务器IP:1420` 即可使用 ClawPanel。
---
## 方式三：Docker 部署
> 📖 Docker 完整教程（Compose、自定义镜像、数据持久化等）见 [Docker 部署指南](docker-deploy.md)
快速启动：
```bash
docker run -d \
--name clawpanel \
--restart unless-stopped \
-p 1420:1420 \
-v clawpanel-data:/root/.openclaw \
node:22-slim \
sh -c "apt-get update && apt-get install -y git && \
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && \
git clone https://github.com/qingchencloud/clawpanel.git /app && \
cd /app && npm install && npx vite --port 1420 --host 0.0.0.0"
```
---
## 配置模型
## 访问 ClawPanel
OpenClaw 需要至少一个 AI 模型才能使用。编辑 `~/.openclaw/openclaw.json`，在 `models.providers` 中添加服务商：
部署完成后，用浏览器打开：
### 示例：添加 OpenAI 兼容服务商
```bash
cat > /tmp/add-provider.py << 'PYEOF'
import json, sys
config_path = f"{sys.path[0]}/../.openclaw/openclaw.json".replace(sys.path[0] + "/../", "")
import os
config_path = os.path.expanduser("~/.openclaw/openclaw.json")
with open(config_path) as f:
config = json.load(f)
# 修改为你的实际服务商信息
provider_id = "my-provider"
config["models"]["providers"][provider_id] = {
"baseUrl": "https://api.openai.com/v1",
"apiKey": "sk-xxxx",
"models": [
{"id": "gpt-4o", "name": "GPT-4o"},
{"id": "gpt-4o-mini", "name": "GPT-4o Mini"}
]
}
# 设置默认模型
config.setdefault("agents", {}).setdefault("defaults", {})["model"] = {
"primary": f"{provider_id}/gpt-4o"
}
with open(config_path, "w") as f:
json.dump(config, f, indent=2, ensure_ascii=False)
print(f"✅ 已添加服务商 {provider_id}")
PYEOF
python3 /tmp/add-provider.py
```
http://服务器IP:1420
```
**或者直接编辑 JSON（更直观）：**
```bash
nano ~/.openclaw/openclaw.json
```
在 `models.providers` 中加入：
```json
{
"models": {
"providers": {
"my-provider": {
"baseUrl": "https://api.openai.com/v1",
"apiKey": "sk-xxxx",
"models": [
{ "id": "gpt-4o", "name": "GPT-4o" },
{ "id": "gpt-4o-mini", "name": "GPT-4o Mini" }
]
}
}
}
}
```
> 支持任何 OpenAI 兼容 API（DeepSeek、通义千问、智谱、Ollama 等），只需修改 `baseUrl` 和 `apiKey`。
ClawPanel 会自动检测本机的 OpenClaw 安装，你可以：
- 管理模型配置（添加/删除/测试 Provider）
- 启动/停止/重启 Gateway
- 查看 Gateway 日志
- 管理 Agent 记忆文件
- 配置备份与恢复
---
## 启动 Gateway
## 进程守护
### 前台运行（调试用）
```bash
openclaw gateway start
```
看到类似输出说明启动成功：
```
Gateway listening on http://0.0.0.0:18789
```
按 `Ctrl+C` 停止。
### 后台运行
```bash
# 使用 nohup
nohup openclaw gateway start > ~/.openclaw/gateway.log 2>&1 &
echo $! > ~/.openclaw/gateway.pid
# 查看日志
tail -f ~/.openclaw/gateway.log
# 停止
kill $(cat ~/.openclaw/gateway.pid)
```
### 验证运行
```bash
# 检查端口是否在监听
ss -tlnp | grep 18789
# 测试 API 响应
curl http://localhost:18789/health
# 从其他机器测试（替换为服务器 IP）
curl http://你的服务器IP:18789/health
```
---
## 开机自启
前台运行会在终端关闭后退出，推荐用 systemd 或 PM2 保持常驻。
### 方式一：systemd（推荐）
创建服务文件：
```bash
sudo tee /etc/systemd/system/openclaw.service << EOF
sudo tee /etc/systemd/system/clawpanel.service << 'EOF'
[Unit]
Description=OpenClaw Gateway
Description=ClawPanel Web - OpenClaw Management Panel
After=network.target
[Service]
Type=simple
User=$USER
Environment=PATH=$(dirname $(which node)):$PATH
ExecStart=$(which openclaw) gateway start
User=root
WorkingDirectory=/opt/clawpanel
ExecStart=/usr/bin/npx vite --port 1420 --host 0.0.0.0
Restart=on-failure
RestartSec=5
WorkingDirectory=$HOME
Environment=NODE_ENV=production
[Install]
WantedBy=multi-user.target
EOF
# 启用并启动
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
# 查看状态
sudo systemctl status openclaw
# 查看日志
journalctl -u openclaw -f
```
**常用命令：**
启用并启动：
```bash
sudo systemctl start openclaw # 启动
sudo systemctl stop openclaw # 停止
sudo systemctl restart openclaw # 重启
sudo systemctl status openclaw # 查看状态
journalctl -u openclaw -f # 实时日志
sudo systemctl daemon-reload
sudo systemctl enable clawpanel
sudo systemctl start clawpanel
```
常用命令：
```bash
sudo systemctl status clawpanel # 查看状态
sudo systemctl restart clawpanel # 重启
sudo journalctl -u clawpanel -f # 查看日志
```
### 方式二：PM2
```bash
# 安装 PM2
npm install -g pm2
# 启动
pm2 start "openclaw gateway start" --name openclaw
# 设置开机自启
cd /opt/clawpanel
pm2 start "npx vite --port 1420 --host 0.0.0.0" --name clawpanel
pm2 save
pm2 startup
# 常用命令
pm2 status # 查看状态
pm2 logs openclaw # 查看日志
pm2 restart openclaw
pm2 stop openclaw
pm2 startup # 开机自启
```
### 方式三：Docker（适合隔离部署）
```bash
docker run -d \
--name openclaw \
--restart unless-stopped \
-p 18789:18789 \
-v ~/.openclaw:/root/.openclaw \
node:22-slim \
sh -c "npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com && openclaw gateway start"
```
> 📖 Docker 完整教程（Compose、自定义镜像、Nginx 反向代理、Ollama 联动等）见 [Docker 部署指南](docker-deploy.md)
---
## 远程管理
## Nginx 反向代理
Gateway 启动后，你可以通过以下方式管理：
### 方式一：ClawPanel 桌面端远程连接
在你的 Windows/Mac 电脑上安装 [ClawPanel](https://github.com/qingchencloud/clawpanel/releases/latest)，打开后在 Gateway 配置页选择「云端模式」，填入服务器地址即可远程管理。
### 方式二：ClawApp 移动端
用手机上的 [ClawApp](https://github.com/qingchencloud/clawapp) 连接 Gateway 地址，随时随地与 AI 对话。
### 方式三：API 直接调用
Gateway 兼容 OpenAI API 格式，任何支持 OpenAI API 的客户端都可以直连：
```bash
# 对话测试
curl http://你的服务器IP:18789/v1/chat/completions \
-H "Content-Type: application/json" \
-H "Authorization: Bearer 你的Token" \
-d '{
"model": "gpt-4o",
"messages": [{"role": "user", "content": "你好"}]
}'
```
**在第三方客户端中使用：**
| 设置项 | 值 |
|--------|------|
| API Base URL | `http://服务器IP:18789/v1` |
| API Key | 你在 `gateway.auth.token` 中设置的密钥 |
| Model | 你配置的模型 ID（如 `gpt-4o`） |
支持 Cherry Studio、ChatBox、LobeChat、BotGem 等所有兼容 OpenAI API 的客户端。
---
## 反向代理
生产环境建议用 Nginx 反向代理，加上 HTTPS。
### Nginx 配置
如果希望用域名 + HTTPS 访问 ClawPanel：
```nginx
server {
listen 443 ssl http2;
server_name ai.example.com;
ssl_certificate /etc/ssl/certs/ai.example.com.pem;
ssl_certificate_key /etc/ssl/private/ai.example.com.key;
listen 80;
server_name panel.yourdomain.com;
location / {
proxy_pass http://127.0.0.1:18789;
proxy_pass http://127.0.0.1:1420;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# WebSocket 支持（聊天流式响应需要）
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 86400;
}
}
```
```bash
sudo nginx -t && sudo systemctl reload nginx
```
> **重要：** 必须配置 WebSocket 升级（`Upgrade` + `Connection`），否则 ClawPanel 无法连接 Gateway。
配置完成后，用 `https://ai.example.com` 替代 IP + 端口访问。
### Cloudflare Tunnel（无需公网 IP）
如果你的服务器没有公网 IP，可以用 [cftunnel](https://github.com/qingchencloud/cftunnel) 一键穿透：
配合 Let's Encrypt 启用 HTTPS：
```bash
# 安装 cftunnel
npm install -g cftunnel
# 创建隧道
cftunnel create --name my-ai --hostname ai.example.com --url http://localhost:18789
# 启动
cftunnel start
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d panel.yourdomain.com
```
---
## 防火墙
## 防火墙配置
如果需要外部访问，记得开放端口：
### UFW (Ubuntu/Debian)
```bash
# UFW（Ubuntu）
sudo ufw allow 18789/tcp
sudo ufw allow 1420/tcp # ClawPanel Web
sudo ufw allow 18789/tcp # OpenClaw Gateway（如需外部直连）
```
# firewalld（CentOS / Fedora）
sudo firewall-cmd --permanent --add-port=18789/tcp
### firewalld (CentOS/RHEL)
```bash
sudo firewall-cmd --permanent --add-port=1420/tcp
sudo firewall-cmd --reload
# iptables
sudo iptables -A INPUT -p tcp --dport 18789 -j ACCEPT
```
> 如果使用了 Nginx 反向代理，只需开放 80/443 端口，不需要开放 18789。
---
## 升级
## 更新升级
### 更新 ClawPanel
```bash
# 升级 OpenClaw
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
# 重启服务
sudo systemctl restart openclaw
# 或
pm2 restart openclaw
cd /opt/clawpanel
git pull origin main
npm install
sudo systemctl restart clawpanel # 或 pm2 restart clawpanel
```
### 更新 OpenClaw
```bash
npm install -g @qingchencloud/openclaw-zh@latest --registry https://registry.npmmirror.com
```
或在 ClawPanel 面板中点击「检查更新」按钮。
---
## 常见问题
### npm install 报错 EACCES（权限不足）
### Q: 端口 1420 被占用？
```bash
# 方式一：修复 npm 全局目录权限
mkdir -p ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
# 查看占用
lsof -i :1420
# 然后重新安装
npm install -g @qingchencloud/openclaw-zh
# 使用其他端口
npx vite --port 3000 --host 0.0.0.0
```
### Gateway 启动后外部无法访问
systemd 服务也需要改 ExecStart 中的端口。
1. 检查 `gateway.bind` 是否为 `"lan"`（不要用 `"loopback"`）
2. 检查防火墙是否放行了端口
3. 云服务器检查安全组规则是否开放端口
### Q: 打开面板显示 "openclaw.json 不存在"？
需要先安装 OpenClaw 并初始化：
```bash
# 验证监听地址
ss -tlnp | grep 18789
# 应显示 0.0.0.0:18789，而不是 127.0.0.1:18789
```
### 端口被占用
```bash
# 查看谁占了端口
sudo lsof -i :18789
# 改用其他端口
jq '.gateway.port = 18790' ~/.openclaw/openclaw.json > /tmp/oc.json && mv /tmp/oc.json ~/.openclaw/openclaw.json
```
### Node.js 版本太低
```bash
node -v
# 如果低于 v18，需要升级
# 使用 nvm 升级
nvm install 22
nvm alias default 22
```
### 内存不足
OpenClaw Gateway 本身占用很小（约 50-100MB），但如果你同时运行 Ollama 等本地模型，建议至少 4GB 内存。
---
## 完整配置参考
```json
{
"mode": "local",
"tools": {
"profile": "full",
"sessions": {
"visibility": "all"
}
},
"gateway": {
"port": 18789,
"bind": "lan",
"mode": "local",
"auth": {
"mode": "token",
"token": "your-secret-token"
}
},
"models": {
"providers": {
"deepseek": {
"baseUrl": "https://api.deepseek.com/v1",
"apiKey": "sk-xxxx",
"models": [
{ "id": "deepseek-chat", "name": "DeepSeek V3" },
{ "id": "deepseek-reasoner", "name": "DeepSeek R1" }
]
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "deepseek/deepseek-chat"
}
}
}
}
```
---
## 一键部署脚本参考
不想记那么多命令？保存以下脚本到服务器，一键搞定：
```bash
#!/bin/bash
set -e
echo "=========================================="
echo " OpenClaw 一键部署脚本"
echo "=========================================="
# 检查 Node.js
if ! command -v node &> /dev/null || [ "$(node -v | sed 's/v//' | cut -d. -f1)" -lt 18 ]; then
echo "📦 安装 Node.js 22..."
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs
fi
echo "✅ Node.js $(node -v)"
# 安装 OpenClaw
echo "📦 安装 OpenClaw..."
npm install -g @qingchencloud/openclaw-zh --registry https://registry.npmmirror.com
echo "✅ OpenClaw $(openclaw --version)"
# 初始化配置
mkdir -p ~/.openclaw
if [ ! -f ~/.openclaw/openclaw.json ]; then
echo "📝 写入默认配置..."
cat > ~/.openclaw/openclaw.json << 'CONF'
{
"mode": "local",
"tools": { "profile": "full", "sessions": { "visibility": "all" } },
"gateway": { "port": 18789, "bind": "lan", "auth": {} },
"models": { "providers": {} }
}
CONF
fi
# 创建 systemd 服务
echo "⚙️ 配置开机自启..."
sudo tee /etc/systemd/system/openclaw.service > /dev/null << SVCEOF
[Unit]
Description=OpenClaw Gateway
After=network.target
[Service]
Type=simple
User=$USER
Environment=PATH=$(dirname $(which node)):$PATH
ExecStart=$(which openclaw) gateway start
Restart=on-failure
RestartSec=5
WorkingDirectory=$HOME
[Install]
WantedBy=multi-user.target
SVCEOF
sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
echo ""
echo "=========================================="
echo " ✅ 部署完成！"
echo "=========================================="
echo ""
echo " Gateway 地址: http://$(hostname -I | awk '{print $1}'):18789"
echo ""
echo " 管理命令:"
echo " sudo systemctl status openclaw # 查看状态"
echo " sudo systemctl restart openclaw # 重启"
echo " journalctl -u openclaw -f # 查看日志"
echo ""
echo " 下一步:"
echo " 1. 编辑 ~/.openclaw/openclaw.json 添加你的模型 API Key"
echo " 2. sudo systemctl restart openclaw"
echo " 3. 用 ClawPanel 或 ClawApp 连接 Gateway"
echo ""
openclaw init
```
保存为 `deploy.sh`，然后 `chmod +x deploy.sh && ./deploy.sh`。
### Q: Gateway 启动/停止按钮不工作？
ClawPanel Web 版在 Linux 上通过 `child_process` 管理进程。确保：
- `openclaw` 命令在 PATH 中
- 运行 ClawPanel 的用户有权限操作进程
```bash
which openclaw # 应输出路径
openclaw --version
```
### Q: 从外网无法访问？
1. 检查防火墙是否放行端口 1420
2. 云服务器需在安全组/防火墙规则中开放端口
3. 推荐使用 Nginx 反向代理 + HTTPS，避免直接暴露端口
### Q: 如何同时启动 Gateway 和 ClawPanel？
Gateway 和 ClawPanel 是独立进程，需要分别启动：
```bash
# 启动 Gateway（后台）
openclaw gateway start &
# 启动 ClawPanel Web
cd /opt/clawpanel
npx vite --port 1420 --host 0.0.0.0
```
或者用 systemd 分别创建两个服务。也可以在 ClawPanel 面板中直接点击「启动」按钮管理 Gateway。
### Q: 与桌面版有什么区别？
| 功能 | 桌面版 (Win/Mac) | Web 版 (Linux) |
|------|-----------------|----------------|
| 配置管理 | ✅ | ✅ |
| Gateway 管理 | ✅ | ✅ |
| 模型测试 | ✅ | ✅ |
| 日志查看 | ✅ | ✅ |
| 备份管理 | ✅ | ✅ |
| Agent 记忆 | ✅ | ✅ |
| ZIP 导出 | ✅ | ❌ |
| 系统托盘 | ✅ | ❌ |
| 自动更新 | ✅ | 手动 git pull |