2026 OpenClaw 倉庫上下文與 Skills 實操
AGENTS.md、bootstrap 注入與 memory_search 調參清單

約 24 分鐘閱讀 · MACCOME

已在跑 Gateway 的開發者把 OpenClaw 接進真實倉庫後,最先撞牆的多半不是「模型叫不醒」,而是AGENTS.md、Skills 與 bootstrap 注入把上下文撐滿,再疊加 memory_search 與日常 memory/*.md 混用,排障時很難判斷「到底是哪一層在燒錢」。本文給出六類可寫進工程公約的痛點promptMode 與 bootstrap 策略對照表三條可與日誌對齊的上下文口徑最小可用的 AGENTS.md 與配置片段六步調參 Runbook;並與《OpenClaw 三平臺安裝》《doctor 裝後排錯》《provider 路由與降級》《Docker 網路分診》《通道接入》互補——前序篇解決起不來與連不上,本篇解決能跑但上下文不可控

六類讓「倉庫智慧體」在兩週內失控的典型坑

OpenClaw 在 2026 年的執行時通常會在啟動階段注入一批倉庫檔案(如 AGENTS.md、Skills、身份與工具說明),並把記憶檢索拆成「啟動注入」與「按需搜尋」兩類路徑。若團隊沒有約定哪些內容進 bootstrap、哪些走 memory_search,很快會出現:每次對話都攜帶巨大靜態字首、工具呼叫鏈變長、費用與延遲同步上升。建議把下列六條與近一週的 token 估算、工具失敗率與平均輪次放在同一儀表板。

  1. AGENTS.md「越寫越長」:把產品史、Roadmap 與運維手冊都塞進單一檔案,bootstrap 階段一次性注入,等價於給每輪對話加固定稅;應拆成「永遠需要」與「按需檢索」兩類。
  2. Skills 目錄缺少索引策略:多個 Skill 重複描述同一工具邊界,模型會在候選工具間猶豫,表現為反覆確認或空轉;需要維護Skill 粒度與互斥說明
  3. promptMode 長期停在 full:子代理、批處理任務仍沿用完整系統提示,浪費上下文;應對照官方文件把 minimal / none 用於合適場景。
  4. memory 檔案當資料庫用:把大塊日誌貼上進 memory/*.md,再依賴 memory_search 全表掃描,IO 與嵌入成本都會上升;應規定摘要進庫、原文走外鏈或物件儲存
  5. 與 provider 路由混為一談:上下文爆炸時若先調模型鏈,容易誤判為「模型能力不足」;應先確認 bootstrap 與工具迴圈,再對照《provider 路由》篇調降級。
  6. 多人共用倉庫不寫所有權:誰改 AGENTS、誰批 Skill PR、誰清理 memory,沒有欄位就會在遠端 Mac 與筆記本之間產生檔案版本漂移

把這六條與《Docker 網路》裡的「Gateway 正常 vs 模型層失敗」分層思路對齊,你會更快判斷問題是上下文策略還是網路/provider

表 1:promptMode、bootstrap 與按需記憶如何分工

下表用於評審:目標是同一倉庫在不同任務形狀下可預測的 token 上限,而不是追求「提示詞寫得漂亮」。具體鍵名以你當前 OpenClaw 版本與配置格式為準。

維度bootstrap 注入(啟動期)memory_search / memory_get(按需)
典型內容AGENTS.md、核心 Skills 摘要、身份與工具邊界日期化筆記、決策記錄、長文附錄
失敗表現每輪都慢、費用高、無關字首多檢索不到、命中過寬、重複讀取
調參抓手總字元上限、分段注入、promptMode索引粒度、檔案命名、摘要策略
與 promptModefull 預設注入最多;minimal 適合子代理省略非必需段不替代 bootstrap;減少「為了省 token 把關鍵邊界只放 memory」
協作約束需要程式碼評審與版本號需要保留審計欄位(誰寫入、何時過期)
遠端 Mac 場景大倉克隆在雲端,注意同步延遲與許可權高頻寫入要防止與本地筆記本搶寫衝突

三條建議寫進 Grafana 或值班表的「上下文口徑」

下列指標可用日誌與粗略 token 估算採集;數值是工程佔位,請用你們基線替換。

  1. bootstrap 有效負載(BEL):單次會話第一條使用者訊息前,靜態字首的等效字元數;若 BEL 長期高於團隊閾值(例如折算後 > 80k 字元的等效負擔),優先拆檔案與收緊 agents.defaults.bootstrapTotalMaxChars 一類上限(鍵名隨版本變化,以官方配置為準)。
  2. 工具迴圈指數(TLI):同一任務內連續「無進展」的工具呼叫次數;TLI 升高往往與 Skills 邊界不清或上下文噪聲相關,而不是 API 429。
  3. 記憶檢索命中率(MRH):memory_search 返回後被模型實際採納的比例(可用人工抽檢或二次確認標記);MRH 過低說明索引或摘要質量欠賬,MRH 過高但 BEL 也高,說明重複內容在多處冗餘存放。

2025–2026 週期內,多模型路由與動態上下文估算(社群 issue 方向)會繼續演進;即便啟用更聰明的路由,倉庫側噪聲仍會直接決定上限,因此 BEL/TLI/MRH 依然值得保留。

若你在評審裡需要向非開發角色解釋,可把 BEL 類比成「每次對話都要先讀完的員工手冊頁數」,把 TLI 類比成「同一件事被反覆請示的次數」:兩者都不解決時,加模型引數往往只是在更貴的紙上繼續印同樣厚的冊子。

markdown
# AGENTS.md(示例:只寫「永遠成立」的邊界,細節放 Skills 或 memory)
## 倉庫角色
- 本倉庫是 xxx 服務;預設分支 main;釋出節奏見 docs/release.md。

## 工具邊界
- 未經評審不改 CI 金鑰與生產配置;資料庫遷移必須雙人複核。

## OpenClaw 約定
- Skills 目錄:.openclaw/skills/(示例路徑,按你們實際)
- 長文決策:寫入 memory/YYYY-MM-decisions.md,並在正文第一行寫摘要。
warning

注意:不要把內部客戶名、未脫敏日誌與完整金鑰寫進會被 bootstrap 的段落;若必須保留,改用按需檢索並限制可見範圍。

六步落地 Runbook:從「能跑」到「可長期維護」

  1. 凍結版本與文件:記錄當前 OpenClaw 與 Gateway 版本,開啟官方文件中 system prompt / bootstrap / memory 相關章節,避免口頭記憶。
  2. 盤點注入源:列出參與 bootstrap 的檔案與 Skills,標註「必須 / 可選 / 應遷移到 memory」三類。
  3. 設 BEL 上限:與團隊約定硬上限與回滾策略;超過上限時優先刪複述性段落,而不是盲目加模型。
  4. 校準 promptMode:為子代理、批處理任務切換到 minimal 或等價策略,並記錄對照實驗(延遲、成功率、費用)。
  5. 整理 memory:把長文改成「摘要 + 指標」;舊日誌歸檔到冷儲存,不在 memory_search 熱區保留全文。
  6. 與 provider/Docker 分層覆盤:若 TLI 仍高,再進入《provider 路由》與《Docker 網路》分診;避免在上下文未收緊前擴大模型池。

Gateway、模型與倉庫上下文:誰該背鍋要先分層

當現象是「偶發超時」時,團隊常急於換模型或加卡;若 BEL 與 TLI 未監控,容易把噪聲上下文誤判為基礎設施不穩。建議沿用《Docker 網路》中的分層順序:先確認 Gateway 與通道健康,再查 provider,再查倉庫側提示詞;這與《通道接入》篇的「三層分診」一致,只是把最上層換成上下文預算

實操上可為每次排障工單增加最小復現四元組:① 當時生效的 promptMode 與已知 BEL 區間;② 最近一次修改 AGENTS/Skills 的合併請求連結;③ memory_search 查詢詞與返回條數;④ Gateway 日誌中與工具呼叫相鄰的片段。四元組齊全時,多數「神秘變慢」能在半小時內判定是提示詞膨脹還是下游依賴,避免在聊天頻道里來回甩鍋。若團隊使用子代理或並行任務,請把每條分支的上下文上限寫進同一臺賬,否則彙總檢視會被「只看主會話」誤導。

為什麼「只在筆記本上跑通」不等於團隊級可維護

個人裝置上的短期試驗往往把大段提示詞與臨時金鑰混在全域性配置裡,難以審計;一旦遷到 CI 或共享遠端 Mac,目錄許可權與同步延遲會讓 AGENTS 與 memory 出現看不見的分叉。把倉庫上下文策略寫清,再配合獨佔的遠端構建/常駐環境,才能把 Agent 工作流變成可覆盤、可交接的工程資產。

純依賴碎片化雲桌面或臨時虛擬機器也能跑 OpenClaw,但在長期線上、固定目錄與低漂移工具鏈上通常不如獨佔物理遠端 Mac 穩定;當團隊要把 Gateway 與大型 monorepo 同機或同區部署時,上下文與磁碟 IO 會同時成為瓶頸。MACCOME 在新加坡、日韓、香港與美東美西提供 Mac Mini M4 / M4 Pro 與彈性租期,適合承載「常駐 Gateway + 大倉克隆」的組合;公開租賃說明可與本文 BEL 上限同一行對齊,先把環境與目錄策略寫死,再迭代 Skills。

試點建議:先在一週內把 BEL 壓到團隊目標區間,再評估是否增加模型檔位或通道數量,避免用更大模型掩蓋倉庫噪聲。

常見問題

安裝與排錯應該先看哪篇?

請按《三平臺安裝》→《doctor 排錯》順序排查;本篇不重複埠與依賴檢查。

網路和模型問題去哪篇?

Docker 與 CLI 請看《Docker 網路分診》;模型鏈請看《provider 路由》。

租賃與幫助文件?

檢視 租賃價格說明幫助中心