# 10. 維運操作手冊

### 10.1 每日確認指令

```bash
# 快速健康檢查
sudo openclaw health

# 查看所有 Docker 容器
sudo docker ps

# 查看 OpenClaw 服務狀態（user service）
systemctl --user status openclaw-gateway

# 查看 skills 狀態（不加 sudo）
openclaw skills list
```

### 10.2 服務重啟

```bash
sudo docker restart nginx           # 重啟 nginx
sudo docker restart cli-proxy-api   # 重啟 CLIProxyAPI
sudo systemctl restart openclaw     # 重啟 OpenClaw
```

### 10.3 OpenClaw 升級

```bash
# 1. 備份設定
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.pre-upgrade-$(date +%Y%m%d)

# 2. 停止 Gateway（避免升級期間衝突）
systemctl --user stop openclaw-gateway

# 3. 下載並執行安裝腳本（自動偵測升級）
#    指定版本：OPENCLAW_VERSION=2026.3.7 NO_PROMPT=1
#    安裝 beta：加 --beta 旗標
curl -fsSL https://openclaw.ai/install.sh -o /tmp/openclaw-install.sh
sudo OPENCLAW_VERSION=<版本號> NO_PROMPT=1 bash /tmp/openclaw-install.sh

# 4. 修正 temp 目錄權限（新版安全檢查要求 700）
chmod 700 /tmp/openclaw-$(id -u)

# 5. 驗證 config JSON 有效
python3 -m json.tool ~/.openclaw/openclaw.json > /dev/null

# 6. 啟動 Gateway
systemctl --user start openclaw-gateway

# 7. 驗證
openclaw --version
systemctl --user status openclaw-gateway
openclaw skills list
```

> **注意**：
> - 升級後若出現 plugin 警告（如 `plugin removed: xxx`），需手動從 `openclaw.json` 的 `plugins.entries` 移除過期條目。
> - Doctor 在無 TTY 環境（如 SSH non-interactive）會跳過 plugin 更新，這是正常的。
> - v2026.3.7 起 browser control server 預設佔用 `gatewayPort + 2`（即 18791），無獨立 config key 可改。若與其他服務衝突需搬移對方。

#### 版本紀錄

| 日期 | 版本 | 備註 |
|------|------|------|
| 2026-02-27 | 2026.2.25 | 升級後 `google-antigravity-auth` plugin 殘留需清理 |
| 2026-02-27 | 2026.2.22 | 回滾（skill 作者建議此版較穩） |
| 2026-03-08 | 2026.3.7 | 正式版升級，browser control port 18791 與 oclaw-auth 衝突，已將 oclaw-auth 搬至 18793 |

### 10.3.1 CLIProxyAPI 升級

```bash
# 手動升級（需 sudo）
cd /home/docker/CLIProxyAPI
sudo git pull --ff-only origin main
sudo docker compose down && sudo docker compose build --no-cache && sudo docker compose up -d

# 驗證
sudo docker compose ps
curl -s -H "Authorization: Bearer <API_KEY>" http://127.0.0.1:8317/v1/models | python3 -c "import json,sys; print(len(json.load(sys.stdin)['data']), 'models')"
```

> **自動更新**：`~/clawd/scripts/update-cliproxyapi.sh`（root crontab，每週日 03:30）
> 自動 git pull + docker rebuild，日誌 `/var/log/cliproxyapi-update.log`

### 10.3.2 自動更新排程（每週日）

| 時間 | 腳本 | Crontab | 說明 |
|------|------|---------|------|
| 02:00 | `nightly-embed.sh` | selig（每天） | 知識庫向量更新 |
| 03:00 | `git pull` OpenClaw Skill | selig | Claude Code skill 更新 |
| 03:30 | `update-cliproxyapi.sh` | root | CLIProxyAPI git pull + Docker rebuild |
| 05:00 | `refresh-llm-list.sh` | selig | 同步 CLIProxyAPI 新模型到 OpenClaw config |

> **順序很重要**：CLIProxyAPI 先更新（03:30），模型列表才能在之後（05:00）抓到新模型。

### 10.3.3 模型冷卻自動切換

`~/clawd/scripts/model-cooldown-watch.sh`（cron 每 12 小時）偵測 CLIProxyAPI 模型 cooldown，自動切 fallback 並用 `at` 排程精準恢復。

```bash
# 手動觸發
bash ~/clawd/scripts/model-cooldown-watch.sh

# 查看日誌
cat /var/log/model-cooldown.log

# 查看排程的恢復任務
at -l
```

> **原理**：API 回 `model_cooldown` + `reset_seconds` → 批量切受影響 agent 到 `agents.defaults.model.fallbacks[0]` → `at now + (reset_seconds+300)/60 minutes` 排程恢復。不依賴 cron 輪詢恢復，避免浪費 API 請求。

### 10.4 日誌查看

```bash
sudo docker logs nginx --tail 50              # nginx 日誌
sudo docker logs cli-proxy-api --tail 50      # CLIProxyAPI 日誌
sudo journalctl -u openclaw -n 50 -f          # OpenClaw 即時日誌
sudo openclaw logs                            # OpenClaw 結構化日誌
```

### 10.5 OpenClaw 管理指令

```bash
# 設備管理
sudo openclaw devices list
sudo openclaw devices approve <id>

# Session 管理
sudo openclaw status
sudo openclaw status --deep

# Cron 任務
sudo openclaw cron list
sudo openclaw cron add --name "test" --cron "0 8 * * *" --session main --system-event "早安"
sudo openclaw cron run <job-id>

# 模型設定
sudo openclaw models status
sudo openclaw doctor

# 安全審計
sudo openclaw security audit
```

### 10.6 備份

```bash
sudo bash ~/backup.sh
# 產生：~/server-backup-YYYYMMDD_HHMMSS.tar.gz（約 80KB）
```

### 10.7 在新機器還原

```bash
scp server-backup-*.tar.gz user@新機器:~/
ssh user@新機器
tar -xzf server-backup-*.tar.gz
sudo bash restore.sh ~/server-backup-YYYYMMDD_HHMMSS
```

### 10.8 Crontab

**selig user**（`crontab -l`）：
```
0 2 * * *   /home/selig/apps/qmd-pg/nightly-embed.sh          # 知識庫向量更新
0 2 * * 0   /home/selig/clawd/scripts/refresh-llm-list.sh     # 每週日更新 CLIProxyAPI 模型清單
*/15 * * *  ~/.acme.sh/acme.sh --cron                          # SSL 憑證自動續期
```

**root**（`sudo crontab -l`）：
```
0 0 * * *   ~/auto_cert_renewal.sh
0 2 * * *   docker exec nginx apk add logrotate && docker exec nginx logrotate -f /etc/logrotate.conf
@reboot     iptables-restore < /etc/iptables/rules.v4
```

### 10.9 開機自啟動架構

| 服務 | 機制 |
|------|------|
| Docker 本身 | systemd enabled |
| nginx | Docker restart: always |
| CLIProxyAPI | Docker restart: unless-stopped |
| OpenClaw Gateway | systemd user `openclaw-gateway.service` enabled |
| OpenClaw Node Host | systemd user `openclaw-node.service` enabled |
| Playwright Chrome | systemd user `playwright-chrome.service` enabled |
| iptables 規則 | crontab @reboot |
| IPv6 停用 | /etc/sysctl.conf 永久設定 |

---

## 附錄：OpenClaw 重要路徑

```
~/.openclaw/openclaw.json           主設定
~/.openclaw/workspace/              Agent 工作目錄
~/.openclaw/agents/main/            主 Agent 資料
  ├── auth-profiles.json            LLM 認證
  ├── sessions/sessions.json        Session 狀態
  └── sessions/*.jsonl              對話記錄
~/.openclaw/credentials/            頻道憑證
~/.openclaw/devices/paired.json     已配對裝置
~/.openclaw/cron/jobs.json          排程任務
~/.openclaw/logs/                   日誌

# Browser Control
~/.openclaw/browser/chrome-extension/       Chrome 擴充套件（snap 不適用）
~/.openclaw/browser/playwright-data/        Playwright Chrome user-data
~/.openclaw/media/browser/                  截圖輸出目錄
~/.cache/ms-playwright/chromium-1208/       Playwright Chromium 二進位

# systemd user services
~/.config/systemd/user/openclaw-gateway.service    Gateway
~/.config/systemd/user/openclaw-node.service       Node Host（需 DISPLAY=:99）
~/.config/systemd/user/playwright-chrome.service   Playwright Chrome（需 DISPLAY=:99）
~/.config/openclaw/gateway.env                     Gateway 環境變數（含 DISPLAY=:99）

/tmp/openclaw-1000/openclaw-YYYY-MM-DD.log  即時日誌（重啟後清除）
```
