# 05-07-openclaw 应用部署

> 本文采用 **Docker 独立部署 + K3s Traefik 反向代理** 的方式集成 OpenClaw：  
> OpenClaw Gateway 本身运行在一台 x86 主机上，K3s 只负责入口统一转发，并不直接在集群内以 Pod 形式运行 OpenClaw。


## TL;DR

- **自动化验收**：`./ansible/bin/verify.sh run 05-07`
- **关键前置**：按本文「前置条件」准备环境变量/Secret/入口 IP
- **成功判据**：达到本文「预期」且 playbook 断言通过
- **排障**：见本文「排障」

## 前置条件

- 已完成基础集群安装：`01-01`、`01-02`
- Traefik 入口已可用（参考 `03-01-k3s-traefik-dashboard.md`）
- 至少一台可访问的 x86 主机，已安装 Docker / Docker Compose v2
- 已规划好访问域名（示例使用 `openclaw.example.com`，请按需替换）

## 操作步骤

1. 在 x86 主机上按官方文档使用 Docker 部署 OpenClaw Gateway 网关
2. 确认在该主机本地可以访问 OpenClaw 控制界面（默认 `http://127.0.0.1:18789/`）
3. 在 K3s 中创建 `Service + Endpoints + Ingress`，将域名流量转发到这台 x86 主机的 OpenClaw 端口

## 在 x86 主机上用 Docker 部署 OpenClaw

参考官方文档：`https://docs.openclaw.ai/zh-CN/install/docker`。

典型快速流程（在 OpenClaw 官方仓库根目录）：

```bash
./docker-setup.sh
```

该脚本会：

- 生成 Gateway 网关令牌并写入 `.env`
- 通过 Docker Compose 启动 Gateway 网关
- 构建 OpenClaw Gateway 镜像

完成后，你可以：

- 在浏览器中访问 `http://127.0.0.1:18789/`，确认控制 UI 可用；
- 如需重新获取带令牌的 URL，可执行：

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

## 在 K3s 中做静态转发

**唯一真源**：[`ansible/files/05-07/openclaw-proxy.yaml`](../ansible/files/05-07/openclaw-proxy.yaml)（按实际 IP、端口、`host` 修改）。

## 部署命令

```bash
kubectl apply -f ansible/files/05-07/openclaw-proxy.yaml
```

## 验证命令

```bash
kubectl get svc,endpoints,ing -n default | grep -i openclaw
curl -I --max-time 3 http://openclaw.example.com/
```

## 预期

- 在 x86 主机本地访问 `http://127.0.0.1:18789/` 可打开 OpenClaw 控制 UI
- 在集群外部访问 `http://openclaw.example.com/` 也能够跳转到同一界面

## 下一步

- 如需为 OpenClaw 容器挂载额外挂载目录或持久化 `/home/node`，请参考官方 Docker 文档中的 `OPENCLAW_EXTRA_MOUNTS` 与 `OPENCLAW_HOME_VOLUME` 说明。
- 返回 `00-00-构建总览.md`，按导航继续阅读其它应用部署文档。

## 排障

- **先看 playbook 输出**：失败时先定位是 deploy/wait/http_check 哪一步。
- **集群侧总览**：`kubectl get nodes -o wide`、`kubectl -n kube-system get pods -o wide`。
- **事件与日志**：`kubectl -n <ns> describe ...`、`kubectl -n <ns> logs ... --tail=200`。