forked from Selig/openclaw-skill
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.
422 lines
12 KiB
Markdown
422 lines
12 KiB
Markdown
# 6. OpenClaw 設定參考
|
||
|
||
### 6.1 主設定結構 `/root/.openclaw/openclaw.json`
|
||
|
||
```json5
|
||
{
|
||
"meta": { "lastTouchedVersion": "2026.2.25" },
|
||
|
||
// Agent 預設設定
|
||
"agents": {
|
||
"defaults": {
|
||
"model": {
|
||
"primary": "google-antigravity/gemini-3-flash"
|
||
},
|
||
"workspace": "/root/.openclaw/workspace",
|
||
"compaction": { "mode": "safeguard" },
|
||
"maxConcurrent": 4,
|
||
"subagents": { "maxConcurrent": 8 }
|
||
}
|
||
},
|
||
|
||
// Telegram 頻道
|
||
"channels": {
|
||
"telegram": {
|
||
"enabled": true,
|
||
"botToken": "<your-bot-token>",
|
||
"dmPolicy": "pairing", // 只有配對裝置可以 DM
|
||
"groupPolicy": "allowlist",
|
||
"streamMode": "partial"
|
||
}
|
||
},
|
||
|
||
// Gateway 設定
|
||
"gateway": {
|
||
"port": 18789,
|
||
"mode": "local",
|
||
"bind": "loopback", // 只接受本機連線，由 nginx 代理
|
||
"auth": {
|
||
"mode": "token",
|
||
"token": "<access-token>"
|
||
}
|
||
},
|
||
|
||
// 訊息設定
|
||
"messages": {
|
||
"ackReactionScope": "group-mentions"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 多 Agent / 多模型設定（獨立 Bot Token 方案）
|
||
|
||
> **踩坑紀錄（2026-02-24 ~ 02-25，v2026.2.17）**
|
||
> - 文件範例用 `agentId`，但實際 schema 要用 **`id`**（否則報 `Unrecognized key: "agentId"`）
|
||
> - `bindings` 需要 **`match` 包裝層**，不是直接放 `channel` / `accountId`
|
||
> - 新 Bot 必須**先完成 config + 重啟 Gateway 後**才按 `/start`，否則配對碼不會回傳
|
||
> - 各獨立 agent 的 `auth-profiles.json` 不會自動共享，需手動複製
|
||
> - **（2026-02-25 新增）** 當使用 `accounts` 區塊後，頂層 `botToken` **不再被當作獨立通道啟動**。所有 Bot（包含主 Bot）都必須放入 `accounts` 內，否則 `channels list` 不會列出、provider 也不會啟動。主 Bot 建議使用 `"default"` 作為 accountId。
|
||
> - **（2026-02-25 新增）** `agents.list` 只有具名 agent（如 life-assistant）時，**隱含的預設 agent 不會掃描 workspace skills**。必須在 `agents.list` 明確加入 `main` agent（含 workspace 路徑），並在 `bindings` 加入 `{ "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } }` 綁定。否則 workspace skills（如 daily-briefing）不會載入。
|
||
|
||
#### 正確的 config 格式（已驗證可用）
|
||
|
||
```json5
|
||
{
|
||
// 1. channels：所有 Bot Token 都放在 accounts 下
|
||
// 頂層 botToken 在使用 accounts 後不再啟動為獨立通道
|
||
"channels": {
|
||
"telegram": {
|
||
"enabled": true,
|
||
"dmPolicy": "pairing",
|
||
"groupPolicy": "allowlist",
|
||
"streamMode": "partial",
|
||
"accounts": {
|
||
"default": { // 主 Bot（@Cimon168_bot）
|
||
"botToken": "<主 Bot Token>"
|
||
},
|
||
"life-bot": { // accountId，自訂名稱
|
||
"botToken": "<新 Bot Token>" // @Cimon_life_bot
|
||
}
|
||
}
|
||
}
|
||
},
|
||
|
||
// 2. agents.list：用 "id" 不是 "agentId"
|
||
// 主 agent 也必須明確列出，否則 workspace skills 不會載入
|
||
"agents": {
|
||
"list": [
|
||
{
|
||
"id": "main", // 主 agent，必須明確列出
|
||
"name": "主 Agent",
|
||
"model": { "primary": "cliapi/gpt-5.3-codex" },
|
||
"workspace": "/home/selig/.openclaw/workspace"
|
||
},
|
||
{
|
||
"id": "life-assistant", // <- 必須用 "id"
|
||
"name": "生活助理",
|
||
"model": { "primary": "cliapi/gpt-5.3-codex" },
|
||
"workspace": "/home/selig/.openclaw/agents/life-assistant"
|
||
}
|
||
],
|
||
"defaults": { "..." }
|
||
},
|
||
|
||
// 3. bindings：match 包裝層（channel + accountId 放 match 內）
|
||
// 每個 account 都需要綁定到對應 agent
|
||
"bindings": [
|
||
{
|
||
"agentId": "main", // 主 Bot → main agent
|
||
"match": {
|
||
"channel": "telegram",
|
||
"accountId": "default"
|
||
}
|
||
},
|
||
{
|
||
"agentId": "life-assistant", // 這裡用 agentId
|
||
"match": { // <- 必須有 match 物件
|
||
"channel": "telegram",
|
||
"accountId": "life-bot" // 對應 accounts 裡的 key
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 安裝步驟
|
||
|
||
```bash
|
||
# 1. BotFather /newbot → 取得 Token
|
||
# 2. 建立 agent 目錄
|
||
mkdir -p ~/.openclaw/agents/<agent-name>/{agent,sessions}
|
||
# 3. 修改 ~/.openclaw/openclaw.json（按上方格式）
|
||
# 4. 重啟 Gateway
|
||
systemctl --user restart openclaw-gateway
|
||
# 5. 確認 log 無錯誤
|
||
journalctl --user -u openclaw-gateway --since "30 sec ago" --no-pager
|
||
# 6. 在 Telegram 新 Bot 發送 /start → 取得配對碼
|
||
# 7. 配對
|
||
openclaw pairing approve telegram <CODE>
|
||
```
|
||
|
||
#### 目前已部署的 Agent
|
||
|
||
| Agent ID | Bot | 用途 | Model |
|
||
|----------|-----|------|-------|
|
||
| main | @Cimon168_bot | 工作/專案/協調 | cliapi/gpt-5.3-codex |
|
||
| life-assistant | @Cimon_life_bot | 生活安排 | cliapi/gpt-5.3-codex |
|
||
|
||
### 6.3 CLIProxyAPI 連線設定
|
||
|
||
CLIProxyAPI 作為 OpenAI-compatible proxy，讓 OpenClaw 可以使用多種 AI 帳號：
|
||
|
||
```json5
|
||
// 在 openclaw.json 加入 custom provider
|
||
{
|
||
"models": {
|
||
"providers": {
|
||
"cliapi": {
|
||
"baseUrl": "http://127.0.0.1:8317/v1",
|
||
"apiKey": "<management-key>",
|
||
"api": "openai-completions"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
CLIProxyAPI 管理介面：`http://192.168.31.169:8317/management.html`
|
||
|
||
### 6.3.1 CLIProxyAPI LLM 輪換規則
|
||
|
||
> 原始碼位置：`sdk/cliproxy/auth/selector.go`、`config.yaml`
|
||
|
||
#### 輪換策略：Round-Robin（按請求次數）
|
||
|
||
**不是依時間輪換**，而是每一個 API request 進來就推進一格。
|
||
|
||
```
|
||
每個 (provider, model) 組合 → 獨立計數器 (cursor)
|
||
cursor → 每次請求 +1
|
||
選取：available[cursor % len(available)]
|
||
```
|
||
|
||
目前設定（`/home/docker/CLIProxyAPI/config.yaml`）：
|
||
|
||
```yaml
|
||
routing:
|
||
strategy: "round-robin" # 另一選項：fill-first（固定燒第一個帳號）
|
||
request-retry: 3 # 失敗後最多重試 3 次（自動換下一個憑證）
|
||
max-retry-interval: 30 # 冷卻等待上限 30 秒
|
||
quota-exceeded:
|
||
switch-project: true # Quota 超限時自動切換帳號
|
||
switch-preview-model: true
|
||
```
|
||
|
||
#### 失敗重試（Fallback）
|
||
|
||
觸發條件（HTTP 狀態碼）：`403 / 408 / 500 / 502 / 503 / 504`
|
||
|
||
- 遇到錯誤 → cursor 繼續推進 → 下次自動選到不同憑證
|
||
- 不是獨立的「備援」邏輯，而是 round-robin 繼續走的自然結果
|
||
|
||
#### 冷卻機制（Quota 超限）
|
||
|
||
- 憑證觸發 **429** → 進入冷卻，指數退避（底數 1s，上限 30min）
|
||
- 冷卻中的憑證從可用池排除，round-robin 只從未冷卻憑證中選
|
||
- 冷卻時間到後自動恢復可用
|
||
|
||
#### 活躍 Provider（目前）
|
||
|
||
| Provider | 模型類型 |
|
||
|----------|---------|
|
||
| Grok (xai) | grok-4 系列、grok-code、grok-imagine |
|
||
| api.navy | qwen3.5、claude-sonnet-4.6、text-embedding |
|
||
|
||
### 6.3.2 CLIProxyAPI 模型清單自動更新
|
||
|
||
當 CLIProxyAPI 新增/移除 AI provider 後，OpenClaw 不會自動偵測到新模型。需要更新 `openclaw.json` 中的 `models.providers.cliapi.models` 陣列。
|
||
|
||
**自動更新腳本**：`~/clawd/scripts/refresh-llm-list.sh`
|
||
|
||
```bash
|
||
# 手動執行
|
||
bash ~/clawd/scripts/refresh-llm-list.sh
|
||
|
||
# 排程：每週日 02:00（crontab）
|
||
0 2 * * 0 /home/selig/clawd/scripts/refresh-llm-list.sh >> /var/log/refresh-llm-list.log 2>&1
|
||
```
|
||
|
||
**腳本流程**：
|
||
1. 從 CLIProxyAPI `/v1/models` 取得最新模型清單
|
||
2. 依模型名稱自動分級（high/mid/low → 不同 cost 設定）
|
||
3. 備份 `openclaw.json` → `openclaw.json.bak`
|
||
4. 更新模型陣列，保留其他設定不變
|
||
5. 重啟 Gateway
|
||
6. 輸出差異（新增/移除的模型）
|
||
|
||
**日誌**：`/var/log/refresh-llm-list.log`
|
||
|
||
**模型分級規則**：
|
||
| 級別 | 關鍵字 | input cost | contextWindow |
|
||
|------|--------|-----------|---------------|
|
||
| high | opus, pro-high, thinking, codex-max, pro-preview | 0.3 | 1M |
|
||
| mid | sonnet, grok, qwen, 預設 | 0.14 | 128K |
|
||
| low | haiku, flash-lite, embedding, mini | 0.07 | 128K |
|
||
| GPT | gpt-* | 0.2 | 128K |
|
||
|
||
### 6.3.3 發送 Telegram 訊息（通知 Agent）
|
||
|
||
```bash
|
||
# 發送訊息到指定群組或用戶
|
||
sudo openclaw message send --channel telegram --target <chat-id> -m "訊息內容"
|
||
|
||
# 群組 ID 對照
|
||
# kaiwu（開物）：-5178404192
|
||
# tiangong（天工）：-5249018181
|
||
# yucheng（玉成）：-5296222979
|
||
|
||
# 範例：通知開物群組
|
||
sudo openclaw message send --channel telegram --target -5178404192 -m "preview 網站已上線"
|
||
|
||
# 附帶圖片
|
||
sudo openclaw message send --channel telegram --target -5178404192 -m "截圖" --media /path/to/image.png
|
||
|
||
# 靜音發送（不觸發通知音）
|
||
sudo openclaw message send --channel telegram --target -5178404192 -m "背景通知" --silent
|
||
```
|
||
|
||
### 6.4 Session Scope 設定
|
||
|
||
```json5
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"session": {
|
||
// 推薦：每個 Telegram 用戶獨立 session，防止資訊洩漏
|
||
"dmScope": "per-channel-peer",
|
||
// 每日 04:00 自動重置 session
|
||
"reset": { "schedule": "0 4 * * *" }
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.5 Auth Profiles（模型認證）
|
||
|
||
位置：`/root/.openclaw/agents/main/auth-profiles.json`
|
||
|
||
```json5
|
||
{
|
||
"version": 1,
|
||
"profiles": {
|
||
"anthropic:manual": {
|
||
"type": "token",
|
||
"provider": "anthropic",
|
||
"token": "sk-ant-..."
|
||
},
|
||
"cliapi:main": {
|
||
"type": "api-key",
|
||
"provider": "openai-compat",
|
||
"apiKey": "<key>",
|
||
"baseUrl": "http://127.0.0.1:8317/v1"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.6 Heartbeat（心跳巡查）
|
||
|
||
Agent 定期自動觸發巡查，執行 `HEARTBEAT.md` 中定義的任務。
|
||
|
||
**預設間隔**（原始碼邏輯）：
|
||
- `gateway.auth.mode = "oauth"` → `1h`
|
||
- 其他模式（token、local） → `30m`
|
||
|
||
**設定方式**：
|
||
```json5
|
||
{
|
||
"agents": {
|
||
"defaults": {
|
||
"heartbeat": {
|
||
"every": "30m" // 所有 agent 預設間隔（支援 "15m", "1h", "2h" 等）
|
||
}
|
||
},
|
||
"list": [
|
||
{
|
||
"id": "main",
|
||
"heartbeat": {
|
||
"every": "15m" // 個別 agent 覆寫
|
||
}
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**指令**：
|
||
```bash
|
||
# 查看目前設定
|
||
openclaw config get agents.defaults.heartbeat
|
||
|
||
# 修改全域間隔
|
||
openclaw config set agents.defaults.heartbeat.every "15m"
|
||
|
||
# 修改單一 agent（需知道 list index，如 main 是 index 0）
|
||
openclaw config set agents.list.0.heartbeat.every "20m"
|
||
```
|
||
|
||
**巡查內容**：定義在各 agent workspace 的 `HEARTBEAT.md`，例如：
|
||
- `~/.openclaw/workspace/HEARTBEAT.md`（主 agent）
|
||
- `~/.openclaw/agents/life-assistant/HEARTBEAT.md`（生活助理）
|
||
|
||
**Telegram 頻道 heartbeat 可見性**：
|
||
```json5
|
||
{
|
||
"channels": {
|
||
"telegram": {
|
||
"heartbeat": "silent" // "visible" | "silent" | "hidden"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.7 Exec Approvals（指令執行審批）
|
||
|
||
Agent 執行 shell 指令（`exec` tool）時的安全策略。**兩個地方都需要設定**：
|
||
|
||
#### 主控制：`openclaw.json` → `tools.exec`
|
||
|
||
這是**真正的 policy 控制點**，決定 agent 能否自動執行指令：
|
||
|
||
```json5
|
||
{
|
||
"tools": {
|
||
"exec": {
|
||
"security": "full", // "deny" | "allowlist" | "full"
|
||
"ask": "off" // "off" | "on-miss" | "always"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
| security | 行為 |
|
||
|----------|------|
|
||
| `deny` | 封鎖所有 exec（sandbox 預設） |
|
||
| `allowlist` | 只允許白名單內的指令（**gateway/node 未設時的預設值**） |
|
||
| `full` | 允許所有指令 |
|
||
|
||
| ask | 行為 |
|
||
|-----|------|
|
||
| `off` | 永不詢問 |
|
||
| `on-miss` | 指令不在白名單時才詢問（**預設值**） |
|
||
| `always` | 每次都詢問 |
|
||
|
||
```bash
|
||
# 設定指令
|
||
openclaw config set tools.exec.security full
|
||
openclaw config set tools.exec.ask off
|
||
# 重啟 Gateway 生效
|
||
systemctl --user restart openclaw-gateway
|
||
```
|
||
|
||
#### 輔助儲存：`~/.openclaw/exec-approvals.json`
|
||
|
||
儲存 allowlist（已核准的指令清單）和 socket 資訊，**不是主要 policy 控制點**：
|
||
|
||
```bash
|
||
# 查看
|
||
openclaw approvals get
|
||
# 設定（覆寫整個檔案）
|
||
openclaw approvals set --stdin < file.json
|
||
```
|
||
|
||
> **踩坑（2026-03-02）**：只設定 `exec-approvals.json` 的 `defaults.security=full` + `defaults.ask=off` **不會生效**。必須在 `openclaw.json` 的 `tools.exec` 設定才是真正的控制點。未設定 `tools.exec` 時，預設為 `security: "allowlist"` + `ask: "on-miss"`，導致 Telegram agent 每次執行指令都需要手動批准，而 Telegram 無法批准 → 120 秒超時。
|
||
|
||
#### Safe Bins（免審批的安全指令）
|
||
|
||
以下 stdin-only 工具即使在 `allowlist` 模式下也不需要白名單：
|
||
- `jq`, `cat`, `head`, `tail`, `cut`, `uniq`, `tr`, `wc`
|
||
- 可透過 `tools.exec.safeBins` 自訂
|
||
- 信任目錄：`/bin`, `/usr/bin`（可透過 `tools.exec.safeBinTrustedDirs` 擴充）
|