openclaw-skill/技術手冊.md

OpenClaw 技術手冊

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

---

章節索引（chapters/）

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

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