Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
140 lines
7.4 KiB
Markdown
140 lines
7.4 KiB
Markdown
# 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`（自動安裝）
|