# OpenClaw 技術手冊
> 本手冊整合實際安裝經驗與 OpenClaw 官方文件，記錄 x550v 伺服器的完整架構。
> 最後更新：2026-03-11

---

## 章節索引（`chapters/`）

> 各章節拆分為獨立檔案，需要深入了解時讀取對應章節。

| 章節 | 檔案 | 內容 | 何時讀取 |
|------|------|------|---------|
| 3 | [03-services.md](chapters/03-services.md) | 服務安裝紀錄（OpenClaw、CLIProxyAPI、nginx） | 安裝/設定服務 |
| 4 | [04-known-issues.md](chapters/04-known-issues.md) | 已知問題與修復（全部踩坑紀錄，15 條） | 遇到問題先查這裡 |
| 5 | [05-agents.md](chapters/05-agents.md) | Agent Team 架構設計（行動任務、生活安排） | 設計/調整 agent 架構 |
| 6 | [06-config.md](chapters/06-config.md) | OpenClaw 設定參考（Multi-Agent、CLIProxyAPI、Session、Heartbeat、Exec） | 修改 openclaw.json |
| 7 | [07-skills.md](chapters/07-skills.md) | Skill 庫（ClawHub、Bundled、知識庫、語音、開發指南） | 新增/管理 skills |
| 8 | [08-plugins.md](chapters/08-plugins.md) | Plugin（memory-lancedb-pro 對話記憶） | 記憶/embedding 問題 |
| 9 | [09-browser.md](chapters/09-browser.md) | Browser Control 瀏覽器控制（架構、Profile、指令、安裝） | 瀏覽器相關操作 |
| 10 | [10-operations.md](chapters/10-operations.md) | 維運操作手冊（升級、備份、Crontab、重要路徑） | 日常維運/升級 |

---

## 1. 系統架構總覽

```
┌─────────────────────────────────────────────────────┐
│                  外部訪問                             │
│   Telegram Bot (@Cimon168_bot)                       │
│   https://oclaw.nature.edu.kg  (OpenClaw WebUI)     │
│   https://cliapi.nature.edu.kg (CLIProxyAPI)        │
└──────────────────┬──────────────────────────────────┘
                   │ HTTPS (nginx 反向代理)
┌──────────────────▼──────────────────────────────────┐
│              x550v 主機 (192.168.31.169)             │
│  ┌─────────────────┐  ┌──────────────────────────┐  │
│  │  nginx (Docker) │  │  CLIProxyAPI (Docker)    │  │
│  │  port 80/443    │  │  port 8317               │  │
│  └────────┬────────┘  └──────────────────────────┘  │
│           │ 反向代理                                  │
│  ┌────────▼────────────────────────────────────┐     │
│  ┌────────▼────────────────────────────────────┐     │
│  │         OpenClaw Gateway (systemd user)     │     │
│  │         port 18789 (loopback)               │     │
│  │         @Cimon168_bot ← main agent         │     │
│  │         @Cimon_life_bot ← life-assistant   │     │
│  └─────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────┘
                   │ Webhook / API
        ┌──────────┴──────────┐
        │                     │
┌───────▼──────┐    ┌─────────▼──────┐
│   VPS-A      │    │   VPS-B        │
│ Claude Code  │    │ OpenCode       │
│ (主要專案)   │    │ Other LLMs     │
│              │    │ (其他專案)     │
└──────────────┘    └────────────────┘
```

### 核心組件說明

| 組件 | 角色 | 技術 | Port |
|------|------|------|------|
| OpenClaw Gateway | AI Agent 核心，連接 Telegram | Node.js 24, systemd user | 18789 |
| OpenClaw Node Host | Browser relay，連接 Gateway 與本機瀏覽器 | systemd user | — |
| Playwright Chrome | 瀏覽器實例（CDP 直連） | systemd user | 18801 |
| CLIProxyAPI | AI API 代理，整合多帳號 | Docker | 8317 |
| nginx | HTTPS 反向代理 | Docker (alpine) | 80/443 |
| Telegram Bot (主) | 工作/專案通訊 | @Cimon168_bot → main | — |
| Telegram Bot (生活) | 生活安排通訊 | @Cimon_life_bot → life-assistant | — |

---

## 2. 伺服器環境

### 主機規格
- **主機名稱**: x550v
- **OS**: Ubuntu (Linux 6.17.0-14-generic)
- **Shell**: bash
- **管理員**: selig（sudo 權限）

### 網路設定
```
介面: enp4s0f2
主要 IP: 192.168.31.169/24  gateway: 192.168.31.1  metric: 100
備用 IP: 192.168.32.32/24   gateway: 192.168.32.1  metric: 200
公網 IP: 106.104.166.28
DNS: 168.95.1.1, 8.8.8.8, 1.1.1.1
```

設定檔：`/etc/netplan/01-network.yaml`

### 目錄結構
```
/home/web/                    # nginx Docker compose root
├── docker-compose.yml        # nginx + PHP + MySQL + Redis
├── nginx.conf
├── conf.d/                   # 各域名 nginx 設定
│   ├── oclaw.nature.edu.kg.conf
│   └── cliapi.nature.edu.kg.conf
├── certs/                    # SSL 憑證 (Let's Encrypt / acme.sh)
├── letsencrypt/              # ACME challenge
├── html/                     # 靜態網頁
└── php-fpm-socket.conf       # PHP-FPM Unix socket 設定覆蓋

/home/selig/preview/           # preview.nature.edu.kg 根目錄
├── index.php                  # 測試頁面
└── <project-name>/            # 各專案子目錄

/home/docker/CLIProxyAPI/     # CLIProxyAPI Docker compose root
├── docker-compose.yml
├── config.yaml               # 主設定（port, auth, 模型）
└── auths/                    # 各 provider 的 OAuth token

/root/.openclaw/              # OpenClaw 設定
├── openclaw.json             # 主設定（Telegram, models, gateway）
├── credentials/              # Telegram pairing 憑證
├── devices/                  # 已配對裝置清單
├── agents/main/              # 主 agent 設定
│   └── auth-profiles.json   # LLM 認證 profile
└── workspace/                # Agent 工作目錄

/home/selig/                  # 維運腳本
├── backup.sh                 # 備份腳本
├── restore.sh                # 還原腳本
└── 備份還原.md
```

### SSL 憑證

| 域名 | 到期日 | 憑證路徑 | 取得方式 |
|------|-------|---------|---------|
| oclaw.nature.edu.kg | 2026-05-20 | `/home/web/certs/oclaw.nature.edu.kg_cert.pem` | certbot standalone |
| cliapi.nature.edu.kg | 2026-05-19 | `/home/web/certs/cliapi.nature.edu.kg_cert.pem` | certbot standalone |
| preview.nature.edu.kg | 2026-05-26 | `/home/web/certs/preview.nature.edu.kg_cert.pem` | acme.sh tls-alpn-01 |

自動續簽：
- certbot：`root crontab: 0 0 * * * ~/auto_cert_renewal.sh`
- acme.sh：`selig crontab: ~/.acme.sh/acme.sh --cron`（自動安裝）