用 OpenClaw 打造個人助理

OpenClaw 是一個支援 WhatsApp + Telegram + Discord + iMessage 的 Pi agent gateway。外掛可加入 Mattermost。這份指南涵蓋「個人助理」設定：一組專用的 WhatsApp 號碼，就像你永遠在線的 agent。

⚠️ 安全第一

你正在讓一個 agent 有能力：

  • 在你的機器上執行指令（取決於你的 Pi 工具設定）
  • 讀寫工作區中的檔案
  • 透過 WhatsApp/Telegram/Discord/Mattermost（外掛）回傳訊息

保守起步：

  • 務必設定 channels.whatsapp.allowFrom（絕對不要在你的個人 Mac 上以完全開放模式執行）。
  • 為助理使用專用的 WhatsApp 號碼。
  • Heartbeat 現在預設每 30 分鐘一次。在你信任設定之前，透過設定 agents.defaults.heartbeat.every: "0m" 來停用。

前置需求

  • OpenClaw 已安裝並完成 onboard — 如果還沒做，請參考 快速上手
  • 第二支手機號碼（SIM/eSIM/預付卡）給助理使用

雙手機設定（建議方式）

你要的是這樣：

flowchart TB
    A["<b>Your Phone (personal)<br></b><br>Your WhatsApp<br>+1-555-YOU"] -- message --> B["<b>Second Phone (assistant)<br></b><br>Assistant WA<br>+1-555-ASSIST"]
    B -- linked via QR --> C["<b>Your Mac (openclaw)<br></b><br>Pi agent"]

如果你把個人 WhatsApp 連到 OpenClaw，所有發給你的訊息都會變成「agent 輸入」。通常這不是你想要的。

5 分鐘快速開始

  1. 配對 WhatsApp Web（顯示 QR code；用助理手機掃描）：
openclaw channels login
  1. 啟動 Gateway（保持執行）：
openclaw gateway --port 18789
  1. 在 ~/.openclaw/openclaw.json 放入最簡設定：
{
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

現在從你的白名單手機發訊息給助理號碼。

當 onboarding 完成後，系統會自動打開 dashboard 並輸出乾淨的（無 token）連結。如果要求驗證，把 gateway.auth.token 裡的 token 貼到 Control UI 設定裡。之後要重開：openclaw dashboard。

給 agent 一個工作區（AGENTS）

OpenClaw 從工作區目錄讀取操作指令和「記憶」。

預設上，OpenClaw 使用 ~/.openclaw/workspace 作為 agent 工作區，並會在設定或首次 agent 執行時自動建立它（加上起始檔案 AGENTS.md、SOUL.md、TOOLS.md、IDENTITY.md、USER.md、HEARTBEAT.md）。BOOTSTRAP.md 只在工作區全新時建立（刪除後不會再出現）。MEMORY.md 是選用的（不會自動建立）；存在時會在一般 session 中載入。Sub-agent session 只會注入 AGENTS.md 和 TOOLS.md。

小技巧：把這個資料夾當作 OpenClaw 的「記憶」，把它做成 git repo（最好是私有的），這樣你的 AGENTS.md 和記憶檔案就有備份。如果已安裝 git，全新的工作區會自動初始化。

openclaw setup

完整工作區配置與備份指南：Agent 工作區 記憶工作流程：記憶

選用：透過 agents.defaults.workspace 選擇不同的工作區路徑（支援 ~）。

{
  agent: {
    workspace: "~/.openclaw/workspace",
  },
}

如果你已經從 repo 中提供自己的工作區檔案，可以完全停用 bootstrap 檔案建立：

{
  agent: {
    skipBootstrap: true,
  },
}

讓它變成「助理」的設定

OpenClaw 預設就是不錯的助理設定，但通常你會想調整：

  • SOUL.md 裡的角色和指令
  • thinking 預設值（如果需要）
  • heartbeat（等你信任它之後）

範例：

{
  logging: { level: "info" },
  agent: {
    model: "anthropic/claude-opus-4-6",
    workspace: "~/.openclaw/workspace",
    thinkingDefault: "high",
    timeoutSeconds: 1800,
    // 先設為 0；之後再啟用。
    heartbeat: { every: "0m" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
    },
  },
  session: {
    scope: "per-sender",
    resetTriggers: ["/new", "/reset"],
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 10080,
    },
  },
}

Sessions 與記憶

  • Session 檔案：~/.openclaw/agents/<agentId>/sessions/{{SessionId}}.jsonl
  • Session 元資料（token 用量、最後路由等）：~/.openclaw/agents/<agentId>/sessions/sessions.json（舊版：~/.openclaw/sessions/sessions.json）
  • /new 或 /reset 為該對話開啟一個新 session（可透過 resetTriggers 設定）。如果單獨發送，agent 會回覆一段簡短的問候來確認重置。
  • /compact [instructions] 壓縮 session 的 context 並回報剩餘的 context 預算。

Heartbeat（主動模式）

預設情況下，OpenClaw 每 30 分鐘執行一次 heartbeat，使用以下 prompt： Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK. 設定 agents.defaults.heartbeat.every: "0m" 來停用。

  • 如果 HEARTBEAT.md 存在但實際上是空的（只有空行和 # Heading 這類 markdown 標題），OpenClaw 會跳過 heartbeat 執行以節省 API 呼叫。
  • 如果檔案不存在，heartbeat 仍然會執行，由模型決定要做什麼。
  • 如果 agent 回覆 HEARTBEAT_OK（可帶一小段附加文字；參見 agents.defaults.heartbeat.ackMaxChars），OpenClaw 會抑制該次 heartbeat 的外送。
  • 預設允許 heartbeat 對 DM 風格的 user:<id> 目標進行投遞。設定 agents.defaults.heartbeat.directPolicy: "block" 可抑制直接目標的投遞，同時保持 heartbeat 執行。
  • Heartbeat 執行完整的 agent 回合 — 越短的間隔燒越多 token。
{
  agent: {
    heartbeat: { every: "30m" },
  },
}

媒體輸入與輸出

傳入的附件（圖片/音訊/文件）可以透過範本呈現給你的指令：

  • {{MediaPath}}（本地暫存檔路徑）
  • {{MediaUrl}}（虛擬 URL）
  • {{Transcript}}（如果啟用了音訊轉錄）

Agent 的外送附件：在獨立一行加上 MEDIA:<path-or-url>（不加空格）。範例：

Here's the screenshot.
MEDIA:https://example.com/screenshot.png

OpenClaw 會擷取這些內容，將它們作為媒體隨文字一起發送。

運維檢查清單

openclaw status          # 本地狀態（憑證、sessions、排隊事件）
openclaw status --all    # 完整診斷（唯讀，可直接貼上）
openclaw status --deep   # 加上 gateway 健康探測（Telegram + Discord）
openclaw health --json   # gateway 健康快照（WS）

日誌位於 /tmp/openclaw/（預設：openclaw-YYYY-MM-DD.log）。

下一步

arrow_back
上一頁
Onboarding
下一頁
Wizard CLI Reference
arrow_forward