{
 "name": "每日早報(bào)",
 "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
 "payload": {
  "kind": "agentTurn",
  "message": "搜索今天的科技和 AI 領(lǐng)域新聞熱點(diǎn)，整理成 5 條簡(jiǎn)報(bào)。每條包含：標(biāo)題、一句話摘要、來(lái)源鏈接。",
  "model": "haiku"
 },
 "sessionTarget": "isolated",
 "delivery": {
  "mode": "announce",
  "channel": "telegram",
  "to": "user:123456789"
 }
}

該配置使用 Haiku 模型生成簡(jiǎn)報(bào)以控制成本，結(jié)果通過(guò) Telegram 投送到指定用戶。

場(chǎng)景二：服務(wù)器健康狀態(tài)巡檢

{
 "name": "服務(wù)巡檢",
 "schedule": { "kind": "every", "everyMs": 3600000 },
 "payload": {
  "kind": "agentTurn",
  "message": "用 curl 檢查以下服務(wù)是否在線：
1. http://localhost:8080
2. http://localhost:3000
3. http://localhost:5432

如果全部正常，不要通知。如果有服務(wù)離線，說(shuō)明哪個(gè)服務(wù)、返回的錯(cuò)誤碼、可能的處理建議。",
  "model": "haiku"
 },
 "sessionTarget": "isolated",
 "delivery": { "mode": "announce" }
}

該配置實(shí)現(xiàn)了"靜默正常"模式——服務(wù)正常時(shí)不會(huì)騷擾用戶，只有異常時(shí)才發(fā)送通知。

場(chǎng)景三：每周項(xiàng)目周報(bào)生成

{
 "name": "項(xiàng)目周報(bào)",
 "schedule": { "kind": "cron", "expr": "0 10 * * 1", "tz": "Asia/Shanghai" },
 "payload": {
  "kind": "agentTurn",
  "message": "讀取 memory/ 目錄下最近 7 天的日志文件，整理成一份周報(bào)。周報(bào)包含：
1. 本周完成的事項(xiàng)（按項(xiàng)目分類）
2. 進(jìn)行中的項(xiàng)目及進(jìn)展
3. 遇到的問(wèn)題及解決方案
4. 下周計(jì)劃
格式簡(jiǎn)潔，使用 bullet points。",
  "model": "sonnet"
 },
 "sessionTarget": "isolated",
 "delivery": {
  "mode": "announce",
  "channel": "discord",
  "to": "channel:987654321"
 }
}

場(chǎng)景四：一次性提醒

通過(guò)自然語(yǔ)言告知 AI 創(chuàng)建，AI 會(huì)自動(dòng)生成對(duì)應(yīng)的 Cron 配置：

"幫我設(shè)置一個(gè) 20 分鐘后的提醒：開(kāi)會(huì)"

OpenClaw 會(huì)自動(dòng)解析并創(chuàng)建類似以下配置：

{
 "name": "開(kāi)會(huì)提醒",
 "schedule": {
  "kind": "at",
  "at": "2026-03-20T1600+08:00"
 },
 "payload": {
  "kind": "systemEvent",
  "text": "開(kāi)會(huì)時(shí)間到了"
 },
 "sessionTarget": "main",
 "deleteAfterRun": true
}

3.5 多渠道投遞配置

投遞模式：

Cron 任務(wù)的delivery.mode參數(shù)控制執(zhí)行結(jié)果的投遞方式：

渠道投遞配置：

{
 "delivery": {
  "mode": "announce",
  "channel": "discord",
  "to": "channel:987654321",
  "bestEffort": true
 }
}

to參數(shù)格式：

channel:：投送到指定頻道

user:：投送給指定用戶

group:：投送到指定群組

bestEffort參數(shù)設(shè)為true時(shí)，投遞失敗不會(huì)重試，適合對(duì)可靠性要求不高的通知場(chǎng)景。

多渠道同時(shí)投遞：

需要同時(shí)投送到多個(gè)渠道時(shí)，可以創(chuàng)建多個(gè) Cron 任務(wù)，或者在任務(wù)消息中指定多個(gè)渠道：

{
 "name": "每日雙渠道通知",
 "schedule": { "kind": "cron", "expr": "0 9 * * *", "tz": "Asia/Shanghai" },
 "payload": {
  "kind": "agentTurn",
  "message": "生成今日摘要，結(jié)果同時(shí)投送到 Discord 和 Telegram",
 },
 "sessionTarget": "isolated",
 "delivery": {
  "mode": "announce",
  "channel": "discord",
  "to": "channel:111111111"
 }
}

如果需要同時(shí)投送多個(gè)渠道，建議在消息中明確說(shuō)明，Agent 會(huì)在執(zhí)行后自動(dòng)處理跨渠道投遞。

第四章：記憶系統(tǒng)與上下文管理

4.1 Compaction 機(jī)制原理

OpenClaw 的 Compaction（壓縮）機(jī)制是解決 AI 長(zhǎng)期對(duì)話失憶問(wèn)題的核心。當(dāng)對(duì)話長(zhǎng)度接近模型的上下文窗口限制時(shí)，OpenClaw 會(huì)自動(dòng)將舊的對(duì)話內(nèi)容壓縮成摘要，釋放 token 空間供后續(xù)對(duì)話使用。

觸發(fā)條件：

Compaction 在以下條件滿足時(shí)觸發(fā)：

對(duì)話歷史總 token 數(shù)接近模型上下文窗口上限

剩余 token 空間低于reserveTokensFloor閾值

壓縮過(guò)程中，已壓縮的對(duì)話會(huì)以摘要形式保留，未壓縮的近期對(duì)話保持原樣。壓縮完成后，新對(duì)話可以繼續(xù)進(jìn)行。

壓縮策略配置：

{
 agents: {
  defaults: {
   compaction: {
    reserveTokensFloor: 20000,
    strategy: "default",
   },
  },
 },
}

reserveTokensFloor表示壓縮后至少保留的最近對(duì)話 token 數(shù)。設(shè)為 20000 時(shí)，壓縮后最近 20K token 的對(duì)話保持原樣，更早的對(duì)話被壓縮為摘要。

手動(dòng)觸發(fā)壓縮：

用戶可以通過(guò)命令手動(dòng)觸發(fā)壓縮，并指定希望保留的重點(diǎn)內(nèi)容：

/compact 重點(diǎn)保留技術(shù)決策和代碼架構(gòu)相關(guān)討論

該命令會(huì)立即對(duì)當(dāng)前對(duì)話進(jìn)行壓縮，保留指令中指定的內(nèi)容優(yōu)先于其他內(nèi)容。

4.2 memoryFlush 配置與閾值設(shè)計(jì)

memoryFlush 機(jī)制：

memoryFlush 是 Compaction 的增強(qiáng)功能，在觸發(fā)壓縮之前先讓 AI 將重要信息寫(xiě)入文件。開(kāi)啟后，AI 不會(huì)因?yàn)閴嚎s而丟失關(guān)鍵記憶。

配置參數(shù)：

{
 agents: {
  defaults: {
   compaction: {
    reserveTokensFloor: 20000,
    memoryFlush: {
     enabled: true,
     softThresholdTokens: 4000,
    },
   },
  },
 },
}

softThresholdTokens: 4000意味著當(dāng)對(duì)話剩余空間降至 4000 token 時(shí)，觸發(fā) memoryFlush。AI 會(huì)將重要信息寫(xiě)入文件，這些信息在壓縮后仍可通過(guò)讀取文件恢復(fù)。

閾值設(shè)計(jì)原則：

softThresholdTokens越小，觸發(fā)越頻繁，AI 有更多 token 用于正常對(duì)話

softThresholdTokens越大，觸發(fā)越早，有更多時(shí)間準(zhǔn)備保存內(nèi)容

推薦值 4000 考慮了保存操作本身需要消耗的 token

驗(yàn)證 memoryFlush 生效：

開(kāi)啟 verbose 模式后，可以在對(duì)話中看到Auto-compaction complete提示：

openclaw gateway restart --verbose

然后在對(duì)話中使用/verbose命令開(kāi)啟 verbose 模式。memoryFlush 執(zhí)行時(shí)不會(huì)有額外提示（靜默執(zhí)行），只有在 compaction 完成后才會(huì)在 verbose 模式下看到提示。

4.3 記憶分層結(jié)構(gòu)設(shè)計(jì)

分層架構(gòu)概述：

OpenClaw 的記憶系統(tǒng)采用分層設(shè)計(jì)，不同層級(jí)的文件承擔(dān)不同的記憶職能：

索引層設(shè)計(jì)：

MEMORY.md是記憶系統(tǒng)的入口，應(yīng)保持精簡(jiǎn)（建議不超過(guò) 40 行）。內(nèi)容應(yīng)包含：

用戶核心信息和偏好

Agent 能力概覽

記憶文件索引（指向其他記憶文件）

當(dāng)前項(xiàng)目的關(guān)鍵上下文

示例結(jié)構(gòu)：

# 核心記憶

## 用戶信息
-姓名：
-時(shí)區(qū)：Asia/Shanghai
-主要語(yǔ)言：中文

## 項(xiàng)目索引
-項(xiàng)目A：memory/projects.md#project-a
-項(xiàng)目B：memory/projects.md#project-b

## 最近重要上下文
-2026-03：完成了系統(tǒng)重構(gòu)，詳見(jiàn) memory/2026-03.md
-當(dāng)前主要任務(wù)：優(yōu)化 Gateway 性能

## 教訓(xùn)索引
-部署相關(guān)：memory/lessons.md#deploy
-配置相關(guān)：memory/lessons.md#config

日志層設(shè)計(jì)：

日志文件命名格式為memory/YYYY-MM-DD.md，按日期歸檔。日志應(yīng)采用結(jié)構(gòu)化格式，便于后續(xù)檢索。

日志格式規(guī)范：

### [PROJECT:項(xiàng)目名] 標(biāo)題

-**結(jié)論**: 一句話核心結(jié)論
-**文件變更**: 涉及的文件路徑
-**教訓(xùn)**: 踩坑點(diǎn)和解決方案（如有）
-**標(biāo)簽**:#tag1#tag2

好日志 vs 壞日志對(duì)比：

壞日志示例（流水賬，信息密度低）：

### 部署
今天部署了項(xiàng)目。先試了直接跑，報(bào)錯(cuò)了。然后查了半天，發(fā)現(xiàn)是端口被占了。最后用 nginx 反代解決了問(wèn)題。

好日志示例（結(jié)構(gòu)化，高信息密度）：

### [PROJECT:MyApp] nginx 反代部署成功

-**結(jié)論**: 通過(guò) nginx 反代部署成功，監(jiān)聽(tīng) 80 端口
-**文件變更**: /etc/nginx/sites-available/myapp
-**教訓(xùn)**: 直接暴露端口不可行，必須走 nginx 反代
-**標(biāo)簽**:#myapp#deploy#nginx

好日志的判斷標(biāo)準(zhǔn)：只看結(jié)論能否快速理解發(fā)生了什么事，不需要閱讀正文。

4.4 向量檢索與 Embedding 配置

memorySearch 機(jī)制：

OpenClaw 的memorySearch功能基于向量語(yǔ)義檢索。當(dāng)用戶詢問(wèn)歷史相關(guān)問(wèn)題時(shí)，Agent 會(huì)調(diào)用 memorySearch 在記憶文件中進(jìn)行語(yǔ)義搜索，返回最相關(guān)的內(nèi)容。

SiliconFlow bge-m3 配置：

國(guó)內(nèi)用戶推薦使用 SiliconFlow 提供的免費(fèi) bge-m3 向量模型：

{
 memorySearch: {
  enabled: true,
  provider: "openai",
  remote: {
   baseUrl: "https://api.siliconflow.cn/v1",
   apiKey: "your-siliconflow-api-key",
  },
  model: "BAAI/bge-m3",
 },
}

bge-m3 模型優(yōu)勢(shì)：

完全免費(fèi)，適合個(gè)人和小型團(tuán)隊(duì)

中英文雙語(yǔ)支持優(yōu)秀

向量維度 1024，精度和性能平衡良好

在中文語(yǔ)義理解任務(wù)上表現(xiàn)優(yōu)異

獲取 SiliconFlow API Key：

訪問(wèn) siliconflow.cn

注冊(cè)賬號(hào)并完成認(rèn)證

進(jìn)入控制臺(tái) → API Keys → 創(chuàng)建新 Key

復(fù)制 Key 并配置到 openclaw.json

向量檢索優(yōu)化策略：

結(jié)構(gòu)化日志的檢索命中率顯著高于非結(jié)構(gòu)化文本。原因在于結(jié)構(gòu)化日志的每個(gè)字段都有明確的語(yǔ)義標(biāo)簽，向量模型能夠更準(zhǔn)確地理解檢索意圖。

提高檢索命中率的實(shí)踐：

標(biāo)簽規(guī)范化：為每個(gè)日志定義統(tǒng)一的標(biāo)簽體系，如#deploy、#config、#bug

關(guān)鍵詞前置：在日志標(biāo)題中包含核心關(guān)鍵詞

結(jié)論獨(dú)立可讀：結(jié)論字段應(yīng)能獨(dú)立表達(dá)完整語(yǔ)義，不依賴正文

定期索引維護(hù)：刪除過(guò)期日志，更新項(xiàng)目狀態(tài)，保持索引新鮮

自動(dòng)記憶維護(hù)：

通過(guò) Heartbeat 任務(wù)實(shí)現(xiàn)自動(dòng)記憶維護(hù)：

{
 "name": "記憶維護(hù)",
 "schedule": { "kind": "every", "everyMs": 604800000 }, // 7天
 "payload": {
  "kind": "agentTurn",
  "message": "讀取 memory/heartbeat-state.json，檢查 lastMemoryMaintenance 字段。如果距今 >= 7 天，執(zhí)行以下維護(hù)任務(wù)：
1. 讀最近 7 天的 memory/YYYY-MM-DD.md 日志
2. 提煉有價(jià)值的信息到對(duì)應(yīng)文件（projects.md / lessons.md）
3. 壓縮已完成一次性任務(wù)的日志為一行結(jié)論
4. 刪除明顯過(guò)期的信息
5. 更新 heartbeat-state.json 的 lastMemoryMaintenance 為今天",
 },
 "sessionTarget": "isolated",
 "delivery": { "mode": "none" },
}

維護(hù)狀態(tài)文件memory/heartbeat-state.json：

{
"lastMemoryMaintenance":"2026-03-01"
}

第五章：多渠道接入運(yùn)維

5.1 Discord Bot 配置與 MESSAGE CONTENT INTENT

配置流程概述：

Discord Bot 接入需要以下步驟：創(chuàng)建應(yīng)用 → 開(kāi)啟 Intent → 獲取 Token → 配置權(quán)限 → 邀請(qǐng)到服務(wù)器 → 配置 openclaw.json。

第一步：創(chuàng)建 Discord 應(yīng)用：

訪問(wèn) Discord Developer Portal（https://discord.com/developers/applications）

點(diǎn)擊 "New Application" → 輸入應(yīng)用名稱 → 點(diǎn)擊 "Create"

在應(yīng)用頁(yè)面左側(cè)點(diǎn)擊 "Bot"

點(diǎn)擊 "Reset Token" → 確認(rèn) → 復(fù)制顯示的 Token（只會(huì)顯示一次）

第二步：開(kāi)啟 Privileged Gateway Intents：

這是 90% 新手踩坑的地方。MESSAGE CONTENT INTENT 必須開(kāi)啟，否則 Bot 收到消息時(shí)無(wú)法讀取內(nèi)容。

在 Bot 頁(yè)面找到 "Privileged Gateway Intents" 部分：

PRESENCE INTENT：讀取用戶在線狀態(tài)（根據(jù)需要開(kāi)啟）

SERVER MEMBERS INTENT：讀取服務(wù)器成員列表（根據(jù)需要開(kāi)啟）

MESSAGE CONTENT INTENT：讀取消息內(nèi)容（必須開(kāi)啟）

將需要的三項(xiàng)設(shè)置為 ON，點(diǎn)擊 "Save Changes"。

第三步：配置 Bot 權(quán)限：

左側(cè)點(diǎn)擊 "OAuth2" → "OAuth2 URL Generator"

Scopes 勾選：bot

Bot Permissions 勾選：

Send Messages

Read Message History

Add Reactions

Use Slash Commands

Embed Links（推薦）

復(fù)制生成的 OAuth2 URL，在瀏覽器中打開(kāi)并授權(quán)到目標(biāo)服務(wù)器

第四步：獲取服務(wù)器 ID：

Discord 客戶端 → 設(shè)置 → 高級(jí) → 開(kāi)啟 "開(kāi)發(fā)者模式"

右鍵服務(wù)器名稱 → 復(fù)制服務(wù)器 ID

第五步：配置 openclaw.json：

{
 channels: {
  discord: {
   token: "your-bot-token",
   allowFrom: [
    "server:123456789012345678",
    "user:987654321098765432",
    "channel:111111111111111111",
   ],
   ackReaction: "",
   dm: {
    enabled: true,
    policy: "pairing",
   },
   guilds: {
    "123456789012345678": {
     historyLimit: 20,
     textChunkLimit: 2000,
    },
   },
  },
 },
}

allowFrom 格式說(shuō)明：

可以組合使用，Bot 只響應(yīng)來(lái)自允許來(lái)源的消息。

ackReaction 配置：

建議使用不常見(jiàn)的 emoji 作為已讀確認(rèn)，便于在大量消息中識(shí)別：

{
 channels: {
  discord: {
   ackReaction: "", // 已讀確認(rèn) emoji
   removeAckAfterReply: false,
  },
 },
}

常見(jiàn)問(wèn)題排查：

驗(yàn)證 Discord 連接：

openclaw gateway status

輸出中應(yīng)顯示 Discord 渠道狀態(tài)為在線。如果顯示離線，檢查：

Token 是否正確

MESSAGE CONTENT INTENT 是否開(kāi)啟

Bot 是否已被移除出服務(wù)器

Gateway 日志中的具體錯(cuò)誤信息

5.2 Telegram Bot 接入

創(chuàng)建 Telegram Bot：

Telegram 搜索 @BotFather

發(fā)送/newbot

按提示輸入 Bot 名稱和用戶名

BotFather 會(huì)返回 Bot Token，格式類似：123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ

獲取用戶 ID：

Telegram 搜索 @userinfobot

向該 Bot 發(fā)送任意消息

Bot 會(huì)返回你的用戶 ID，格式類似：123456789

配置 openclaw.json：

{
 channels: {
  telegram: {
   botToken: "123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ",
   allowFrom: ["123456789"],
   dm: {
    enabled: true,
    policy: "pairing",
   },
   historyLimit: 50,
   replyToMode: "first",
   linkPreview: true,
   streamMode: "partial",
  },
 },
}

dm.policy 選項(xiàng)：

Telegram + Discord 多渠道同時(shí)在線：

{
 channels: {
  discord: {
   token: "discord-bot-token",
   allowFrom: ["server:123456789"],
   ackReaction: "",
  },
  telegram: {
   botToken: "telegram-bot-token",
   allowFrom: ["123456789"],
  },
 },
}

多渠道配置時(shí)，消息路由自動(dòng)處理——來(lái)自哪個(gè)渠道的請(qǐng)求，響應(yīng)就發(fā)送到哪個(gè)渠道。

5.3 多渠道消息路由機(jī)制

路由規(guī)則：

OpenClaw 的消息路由基于以下規(guī)則：

每條消息攜帶來(lái)源渠道標(biāo)識(shí)

路由決策根據(jù)消息來(lái)源和配置中的 bindings 確定目標(biāo) Agent

響應(yīng)總是發(fā)送到消息來(lái)源的同一渠道

多 Agent 綁定：

如果需要不同渠道或不同賬號(hào)綁定不同的 Agent：

{
 agents: {
  list: [
   { id: "main", default: true, workspace: "~/.openclaw/workspace-main" },
   { id: "work", workspace: "~/.openclaw/workspace-work" },
  ],
 },
 bindings: [
  { agentId: "main", match: { channel: "telegram", accountId: "personal" } },
  { agentId: "work", match: { channel: "telegram", accountId: "biz" } },
  { agentId: "main", match: { channel: "discord" } },
 ],
 channels: {
  telegram: {
   accounts: {
    personal: { botToken: "token1" },
    biz: { botToken: "token2" },
   },
  },
 },
}

跨渠道身份鏈接：

如果用戶同時(shí)使用多個(gè)渠道并希望共享上下文：

{
 session: {
  identityLinks: [
   { key: "user-alice", channels: ["telegram:123456", "discord:987654"] },
  ],
 },
}

配置后，來(lái)自這兩個(gè)渠道的消息會(huì)被識(shí)別為同一用戶，共享會(huì)話歷史。

5.4 平臺(tái)格式適配規(guī)范

各平臺(tái)格式支持差異：

格式適配規(guī)則配置：

在 AGENTS.md 中添加平臺(tái)格式適配規(guī)范：

## 平臺(tái)格式

### Discord
-可以使用完整 Markdown
-代碼塊使用 triple backtick 包裹
-多鏈接使用<>包裹防止預(yù)覽刷屏
-支持 embed 格式

### Telegram
-支持 Markdown（部分標(biāo)簽）
-代碼塊使用 triple backtick 包裹
-不支持 Markdown 表格，用 bullet list 代替
-支持內(nèi)聯(lián)按鈕

### WhatsApp
-不支持 Markdown 表格，使用 bullet list
-代碼塊使用 inline code（單反引號(hào)）
-鏈接會(huì)自動(dòng)轉(zhuǎn)換，但不支持預(yù)覽

輸出格式動(dòng)態(tài)調(diào)整：

AI 會(huì)根據(jù)消息來(lái)源自動(dòng)調(diào)整輸出格式。如果需要顯式控制：

## 輸出格式控制

當(dāng)被要求"用表格展示"時(shí)：
-如果是 Discord：用 Markdown 表格
-如果是 Telegram 或 WhatsApp：用等寬字符模擬表格或改用 bullet list

第六章：配置速查與故障排查

6.1 核心配置參數(shù)速查表

Gateway 核心配置：

Agent 核心配置：

渠道配置速查：

工具配置：

流式輸出配置：

6.2 常見(jiàn)故障診斷流程

故障一：Gateway 無(wú)法啟動(dòng)

診斷步驟：

# 1. 檢查配置文件語(yǔ)法
openclaw doctor

# 2. 檢查端口是否被占用
ss -tlnp | grep 18789

# 3. 查看詳細(xì)錯(cuò)誤日志
openclaw gateway start --verbose 2>&1

# 4. 檢查日志文件
tail -100 /var/log/openclaw/gateway.log

常見(jiàn)原因：

JSON5 語(yǔ)法錯(cuò)誤（注釋格式問(wèn)題、尾隨逗號(hào)問(wèn)題）

端口被占用

auth token 未設(shè)置但綁定到非 loopback 地址

workspace 目錄權(quán)限不足

故障二：渠道 Bot 不工作

通用診斷流程：

# 1. 檢查渠道狀態(tài)
openclaw gateway status

# 2. 查看渠道連接日志
openclaw logs --grep"discord|telegram|whatsapp"--lines 50

# 3. 測(cè)試渠道 API 連通性
# Discord: 檢查 Bot 是否在線
# Telegram: curl https://api.telegram.org/bot/getMe

Discord 專項(xiàng)檢查：

確認(rèn) MESSAGE CONTENT INTENT 已開(kāi)啟

確認(rèn) Bot 未被服務(wù)器禁言或移除

確認(rèn) Bot 在目標(biāo)頻道有 Send Messages 權(quán)限

Telegram 專項(xiàng)檢查：

確認(rèn) Bot Token 正確

確認(rèn) Bot 未被 Ban

確認(rèn)用戶 ID 在 allowFrom 列表中

故障三：Cron 任務(wù)不觸發(fā)

診斷步驟：

# 1. 檢查任務(wù)列表
openclaw cron list

# 2. 查看任務(wù)詳情
openclaw cron list --verbose

# 3. 檢查執(zhí)行歷史
openclaw cron runs --id <任務(wù)ID>

# 4. 檢查調(diào)度器狀態(tài)
openclaw gateway status

常見(jiàn)原因：

時(shí)區(qū)問(wèn)題：未設(shè)置tz字段，默認(rèn)使用 UTC

任務(wù)被禁用：enabled: false

delivery.mode 問(wèn)題：不設(shè)為announce時(shí)任務(wù)靜默執(zhí)行

調(diào)度器未運(yùn)行：cron.enabled: false

故障四：AI 失憶

診斷步驟：

# 1. 檢查 memoryFlush 配置
openclaw config get agents.defaults.compaction

# 2. 檢查記憶文件是否存在
ls -la ~/.openclaw/workspace/memory/

# 3. 檢查 memorySearch 是否配置
openclaw config get memorySearch

# 4. 查看 compaction 觸發(fā)日志
openclaw logs --grep"compaction|memoryFlush"--lines 50

常見(jiàn)原因：

memoryFlush 未開(kāi)啟

softThresholdTokens 設(shè)置過(guò)小

記憶文件寫(xiě)入權(quán)限問(wèn)題

memorySearch 未配置導(dǎo)致檢索不到歷史

故障五：消息無(wú)響應(yīng)

診斷步驟：

# 1. 檢查 allowFrom 配置
openclaw config get channels..allowFrom

# 2. 檢查消息是否被正確接收
openclaw logs --grep"message|inbound"--lines 50

# 3. 檢查 session 狀態(tài)
openclaw sessions list

常見(jiàn)原因：

消息來(lái)源不在 allowFrom 列表

DM policy 問(wèn)題（pairing 模式未完成配對(duì)）

用戶被禁言或 Bot 被拉黑

6.3 證據(jù)鏈?zhǔn)降慕Y(jié)論驗(yàn)證

配置生效驗(yàn)證：

每個(gè)配置變更都應(yīng)通過(guò)以下方式驗(yàn)證生效：

重啟驗(yàn)證：變更配置后執(zhí)行openclaw gateway restart，觀察日志無(wú)錯(cuò)誤輸出

狀態(tài)驗(yàn)證：openclaw gateway status顯示所有渠道在線

功能驗(yàn)證：實(shí)際測(cè)試配置的功能點(diǎn)（如發(fā)送消息測(cè)試 Cron 投遞）

日志證據(jù)收集：

故障排查時(shí)，應(yīng)收集以下日志作為證據(jù)：

# 獲取時(shí)間范圍內(nèi)的日志
openclaw logs --since"2026-03-20 1000"--until"2026-03-20 1200"> /tmp/gateway-logs.txt

# 獲取特定關(guān)鍵詞日志
openclaw logs --grep"error|warn"--lines 200 > /tmp/errors.txt

# 導(dǎo)出完整狀態(tài)
openclaw gateway status --deep > /tmp/status.txt

配置回滾流程：

重大配置變更前，應(yīng)先備份當(dāng)前配置：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d-%H%M%S)

如需回滾：

# 查看備份列表
ls -la ~/.openclaw/openclaw.json.backup-*

# 回滾到指定備份
cp ~/.openclaw/openclaw.json.backup-20260320-143000 ~/.openclaw/openclaw.json

# 重啟 Gateway
openclaw gateway restart

健康檢查基準(zhǔn)線：

建立正常運(yùn)行時(shí)的基準(zhǔn)數(shù)據(jù)，便于故障時(shí)對(duì)比：

# 記錄基準(zhǔn)狀態(tài)
openclaw gateway status --deep > /tmp/status-baseline.txt

# 記錄 Cron 任務(wù)列表
openclaw cron list > /tmp/cron-baseline.txt

附錄一：配置清單

部署前檢查清單

[ ] 配置文件 JSON5 語(yǔ)法驗(yàn)證通過(guò)（openclaw doctor）

[ ] Gateway 認(rèn)證 Token 已設(shè)置

[ ] workspace 目錄權(quán)限正確

[ ] 進(jìn)程管理器已配置（systemd）

[ ] 日志輪轉(zhuǎn)已配置

[ ] 所有渠道 Token/Key 已配置

[ ] memorySearch 已配置（推薦 SiliconFlow bge-m3）

[ ] 心跳活躍時(shí)段已設(shè)置（避免半夜打擾）

運(yùn)維巡檢清單

[ ]openclaw gateway status所有渠道在線

[ ]openclaw cron list無(wú)禁用任務(wù)異常

[ ] 磁盤(pán)使用率 < 85%

[ ] 日志文件大小正常，無(wú)積壓

[ ] 記憶文件定期更新

安全加固清單

[ ] Gateway 綁定到 loopback

[ ] 認(rèn)證 Token 足夠復(fù)雜

[ ] allowFrom 限制最小必要范圍

[ ] 日志中無(wú)敏感信息泄露（檢查 redactSensitive 配置）

[ ] 定期更新 OpenClaw 版本

附錄二：命令速查

Gateway 管理

openclaw gateway start     # 啟動(dòng) Gateway
openclaw gateway restart   # 重啟 Gateway
openclaw gateway stop     # 停止 Gateway
openclaw gateway reload    # 熱重載配置
openclaw gateway health    # 存活性檢查
openclaw gateway status    # 狀態(tài)檢查
openclaw gateway status --deep# 深度狀態(tài)檢查

日志管理

openclaw logs --follow    # 實(shí)時(shí)跟蹤
openclaw logs --lines 100   # 最近 100 行
openclaw logs --grep"error" # 過(guò)濾關(guān)鍵詞

Cron 管理

openclaw cron list      # 任務(wù)列表
openclaw cron runs --id  # 執(zhí)行歷史
openclaw cron edit  --disable# 禁用任務(wù)
openclaw cron edit  --enable # 啟用任務(wù)
openclaw cron run --id  --force # 手動(dòng)觸發(fā)

配置管理

openclaw config validate    # 驗(yàn)證配置
openclaw config get    # 獲取配置項(xiàng)
openclaw doctor        # 診斷檢查

附錄三：配置文件模板

{
 // Workspace 配置
 agents: {
  defaults: {
   workspace: "~/.openclaw/workspace",
   repoRoot: "~/.openclaw/workspace",
   skipBootstrap: false,
   model: {
    primary: "provider/claude-sonnet-4",
    fallbacks: ["provider/claude-haiku-4"],
   },
   imageModel: "provider/claude-sonnet-4",
   timeoutSeconds: 600,
   compaction: {
    reserveTokensFloor: 20000,
    memoryFlush: {
     enabled: true,
     softThresholdTokens: 4000,
    },
   },
   heartbeat: {
    every: "30m",
    target: "last",
    activeHours: {
     start: "08:00",
     end: "23:00",
    },
   },
   blockStreamingDefault: "on",
   blockStreamingBreak: "text_end",
   blockStreamingChunk: {
    minChars: 200,
    maxChars: 1500,
   },
  },
 },

 // Gateway 配置
 gateway: {
  port: 18789,
  bind: "loopback",
  auth: {
   mode: "token",
   token: "your-secret-token",
  },
  reload: {
   mode: "hybrid",
  },
 },

 // 日志配置
 logging: {
  level: "info",
  consoleStyle: "pretty",
  redactSensitive: "tools",
 },

 // 渠道配置
 channels: {
  discord: {
   token: "your-discord-bot-token",
   allowFrom: ["server:your-server-id"],
   ackReaction: "",
   dm: {
    enabled: true,
    policy: "pairing",
   },
   historyLimit: 20,
   textChunkLimit: 2000,
  },
  telegram: {
   botToken: "your-telegram-bot-token",
   allowFrom: ["your-user-id"],
   dm: {
    enabled: true,
    policy: "pairing",
   },
   historyLimit: 50,
   replyToMode: "first",
   linkPreview: true,
   streamMode: "partial",
  },
 },

 // 向量檢索配置
 memorySearch: {
  enabled: true,
  provider: "openai",
  remote: {
   baseUrl: "https://api.siliconflow.cn/v1",
   apiKey: "your-siliconflow-api-key",
  },
  model: "BAAI/bge-m3",
 },

 // 工具配置
 tools: {
  exec: {
   enabled: true,
  },
  web: {
   search: {
    enabled: true,
   },
  },
  media: {
   image: {
    enabled: true,
   },
  },
 },

 // Cron 配置
 cron: {
  enabled: true,
  maxConcurrentRuns: 2,
 },
}