Moltbot 文件

Appearance

Session 管理 ​

Moltbot 將每個 agent 的一個直接對話 session 視為主要 session。直接對話會合併為 agent:<agentId>:<mainKey>（預設為 main），而群組/頻道對話則有自己的金鑰。會遵循 session.mainKey 設定。

使用 session.dmScope 控制直接訊息的分組方式：

  • main（預設）：所有 DM 共享主 session 以保持連續性。
  • per-peer：跨頻道按發送者 id 隔離。
  • per-channel-peer：按頻道 + 發送者隔離（建議用於多使用者收件箱）。
  • per-account-channel-peer：按帳號 + 頻道 + 發送者隔離（建議用於多帳號收件箱）。

使用 session.identityLinks 將提供者前綴的對等 id 對應到標準身分，使同一人在使用 per-peer、per-channel-peer 或 per-account-channel-peer 時跨頻道共享 DM session。

Gateway 是真相來源 ​

所有 session 狀態由 gateway 擁有（"主" Moltbot）。UI 客戶端（macOS 應用程式、WebChat 等）必須向 gateway 查詢 session 清單和 token 計數，而非讀取本機檔案。

  • 在遠端模式中，您關心的 session 儲存位於遠端 gateway 主機上，而非您的 Mac。
  • UI 中顯示的 token 計數來自 gateway 的儲存欄位（inputTokens、outputTokens、totalTokens、contextTokens）。客戶端不會解析 JSONL 記錄來「修正」總數。

狀態存放位置 ​

  • 在 gateway 主機上：
    • 儲存檔案：~/.clawdbot/agents/<agentId>/sessions/sessions.json（每個 agent）。
  • 記錄：~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl（Telegram 主題 session 使用 .../<SessionId>-topic-<threadId>.jsonl）。
  • 儲存是一個對映 sessionKey -> { sessionId, updatedAt, ... }。刪除條目是安全的；它們會按需重新建立。
  • 群組條目可能包含 displayName、channel、subject、room 和 space 以在 UI 中標記 session。
  • Session 條目包含 origin 中繼資料（標籤 + 路由提示），讓 UI 可以解釋 session 來源。
  • Moltbot 不會讀取舊版 Pi/Tau session 資料夾。

Session 修剪 ​

Moltbot 在 LLM 呼叫之前從記憶體中的上下文中修剪舊工具結果（預設）。這不會重寫 JSONL 歷史記錄。參見 /concepts/session-pruning。

預壓縮記憶體刷新 ​

當 session 接近自動壓縮時，Moltbot 可以執行靜默記憶體刷新回合，提醒模型將持久筆記寫入磁碟。這僅在工作區可寫時執行。參見 Memory 和 Compaction。

傳輸對映 → session 金鑰 ​

  • 直接對話遵循 session.dmScope（預設 main）。
    • main：agent:<agentId>:<mainKey>（跨裝置/頻道的連續性）。
      • 多個電話號碼和頻道可以對映到相同的 agent 主金鑰；它們作為進入一個對話的傳輸。
    • per-peer：agent:<agentId>:dm:<peerId>。
    • per-channel-peer：agent:<agentId>:<channel>:dm:<peerId>。
    • per-account-channel-peer：agent:<agentId>:<channel>:<accountId>:dm:<peerId>（accountId 預設為 default）。
    • 如果 session.identityLinks 符合提供者前綴的對等 id（例如 telegram:123），標準金鑰會取代 <peerId>，使同一人跨頻道共享 session。
  • 群組對話隔離狀態：agent:<agentId>:<channel>:group:<id>（房間/頻道使用 agent:<agentId>:<channel>:channel:<id>）。
    • Telegram 論壇主題在群組 id 後附加 :topic:<threadId> 以進行隔離。
    • 舊版 group:<id> 金鑰仍被識別以進行遷移。
  • 入站上下文可能仍使用 group:<id>；頻道從 Provider 推斷並正規化為標準 agent:<agentId>:<channel>:group:<id> 形式。
  • 其他來源：
    • Cron 作業：cron:<job.id>
    • Webhooks：hook:<uuid>（除非由 hook 明確設定）
    • Node 執行：node-<nodeId>

生命週期 ​

  • 重設策略：session 會重複使用直到過期，過期會在下一則入站訊息時評估。
  • 每日重設：預設為 gateway 主機本機時間上午 4:00。當 session 的最後更新早於最近的每日重設時間時，該 session 就過期了。
  • 閒置重設（選用）：idleMinutes 新增滑動閒置視窗。當同時設定每日和閒置重設時，先過期的強制新 session。
  • 舊版僅閒置：如果您設定 session.idleMinutes 而沒有任何 session.reset/resetByType 設定，Moltbot 會保持僅閒置模式以保持向後相容性。
  • 每類型覆寫（選用）：resetByType 讓您為 dm、group 和 thread session 覆寫策略（thread = Slack/Discord threads、Telegram 主題、連接器提供的 Matrix threads）。
  • 每頻道覆寫（選用）：resetByChannel 覆寫頻道的重設策略（適用於該頻道的所有 session 類型，優先於 reset/resetByType）。
  • 重設觸發：精確的 /new 或 /reset（加上 resetTriggers 中的任何額外項）會啟動新的 session id 並傳遞訊息的其餘部分。/new <model> 接受模型別名、provider/model 或提供者名稱（模糊比對）以設定新 session 模型。如果單獨傳送 /new 或 /reset，Moltbot 會執行簡短的「hello」問候回合以確認重設。
  • 手動重設：從儲存中刪除特定金鑰或移除 JSONL 記錄；下一則訊息會重新建立它們。
  • 隔離的 cron 作業總是為每次執行建立新的 sessionId（無閒置重複使用）。

傳送策略（選用） ​

封鎖特定 session 類型的傳遞，而無需列出個別 id。

json5
{
  session: {
    sendPolicy: {
      rules: [
        { action: "deny", match: { channel: "discord", chatType: "group" } },
        { action: "deny", match: { keyPrefix: "cron:" } }
      ],
      default: "allow"
    }
  }
}

執行時覆寫（僅限擁有者）：

  • /send on → 允許此 session
  • /send off → 拒絕此 session
  • /send inherit → 清除覆寫並使用設定規則

將這些作為獨立訊息傳送以便註冊。

設定（選用重新命名範例） ​

json5
// ~/.clawdbot/moltbot.json
{
  session: {
    scope: "per-sender",      // 保持群組金鑰分開
    dmScope: "main",          // DM 連續性（為共享收件箱設定 per-channel-peer/per-account-channel-peer）
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"]
    },
    reset: {
      // 預設：mode=daily, atHour=4（gateway 主機本機時間）。
      // 如果您也設定 idleMinutes，先過期的優先。
      mode: "daily",
      atHour: 4,
      idleMinutes: 120
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      dm: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 }
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 }
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.clawdbot/agents/{agentId}/sessions/sessions.json",
    mainKey: "main",
  }
}

檢查 ​

  • moltbot status — 顯示儲存路徑和最近的 sessions。
  • moltbot sessions --json — 傾印每個條目（使用 --active <minutes> 篩選）。
  • moltbot gateway call sessions.list --params '{}' — 從執行中的 gateway 取得 sessions（為遠端 gateway 存取使用 --url/--token）。
  • 在對話中作為獨立訊息傳送 /status，查看 agent 是否可達、session 上下文使用了多少、目前的 thinking/verbose 切換，以及您的 WhatsApp web 憑證上次重新整理的時間（有助於發現重新連結需求）。
  • 傳送 /context list 或 /context detail 查看系統提示和注入的工作區檔案中的內容（以及最大的上下文貢獻者）。
  • 作為獨立訊息傳送 /stop 以中止目前的執行，清除該 session 的佇列後續，並停止從中產生的任何 sub-agent 執行（回覆包含停止計數）。
  • 作為獨立訊息傳送 /compact（選用說明）以總結較舊的上下文並釋放視窗空間。參見 /concepts/compaction。
  • 可以直接開啟 JSONL 記錄以檢視完整回合。

提示 ​

  • 保持主金鑰專用於 1:1 流量；讓群組保留自己的金鑰。
  • 在自動化清理時，刪除個別金鑰而非整個儲存，以保留其他地方的上下文。

Session 來源中繼資料 ​

每個 session 條目在 origin 中記錄它的來源（盡力而為）：

  • label：人類可讀標籤（從對話標籤 + 群組主題/頻道解析）
  • provider：正規化的頻道 id（包括擴充功能）
  • from/to：來自入站信封的原始路由 id
  • accountId：提供者帳號 id（當多帳號時）
  • threadId：當頻道支援時的 thread/topic id

origin 欄位會為直接訊息、頻道和群組填入。如果連接器僅更新傳遞路由（例如，保持 DM 主 session 新鮮），它仍應提供入站上下文，以便 session 保留其解釋器中繼資料。擴充功能可以透過在入站上下文中傳送 ConversationLabel、GroupSubject、GroupChannel、GroupSpace 和 SenderName，並呼叫 recordSessionMetaFromInbound（或將相同的上下文傳遞給 updateLastRoute）來執行此操作。

基於 MIT 授權發布

Copyright © 2026 Moltbot Taiwan