2026-05-15 OpenClaw 工作區 AGENTS.md 作為倉庫說明：在無頭租用 Apple Silicon 雲端 Mac（HK / JP / KR / SG / US）上的實務

當 OpenClaw 能讀完整個單體倉庫時，槓桿最高的文件往往不是再多一層 JSON，而是放在 Git 根目錄、經過約束的 AGENTS.md：同時服務工程師與模型，描述「正常態」應長什麼樣子。在香港、東京、首爾、新加坡與美國租用的 Mac mini M4 上，同一台主機可能並行跑 xcodebuild、簽章樹與可改 Swift 的助理。2026-05-15 本文把 AGENTS.md 放入完整策略堆疊：與 工作區白名單與單體護欄 對齊，與 多智能體 agents.json 角色拆分 分工，並與 onboard、launchd、doctor 分流 同倉演進——但避免把機器可讀的工具表逐行抄進 Markdown。

在已有 agents.json 時，為何仍要倉庫級 AGENTS.md

agents.json 承載身分、模型與工具面，是網關應確定性解析的契約。AGENTS.md 回答另一組問題：本倉建置何種產品、哪些目錄不可任意碰觸、哪條測試指令具權威、回滾如何分段、風險操作要叫醒誰。共用租用機構建機上，這類敘述能在事故 diff 呈現「意圖」，而不僅是 JSON 陣列。正文控制在約兩分鐘可朗讀完；更長流程放入 技能包，並在此寫明入口路徑與觸發條件。

策略堆疊：AGENTS.md 相對白名單與 agents.json 的位置

由上而下可理解為：傳輸與頻道、網關路由、工作區白名單、智能體執行時 JSON、選用技能，最後才是倉庫說明。AGENTS.md 最接近「社會契約」——不能推翻預設拒絕的檔案系統策略，但要解釋根路徑為何存在、助理在其中的預期行為。多智能體共用一機時各畫像仍讀同一倉庫，因此 AGENTS.md 應維持人格中立，由 agents.json 縮小工具面。

層級	主要載體	責任方	AGENTS.md 應…
檔案系統護欄	工作區白名單	平台／安全	依路徑引用根目錄，不得另寫一套衝突規則
執行時策略	agents.json	自動化負責人	解釋各畫像意圖，並連結 Git 內 JSON 路徑
流程深度	技能／手冊	服務團隊	以穩定標題做索引，避免貼上多頁 shell
人＋模型脈絡	AGENTS.md	倉庫維護者	寫清使命、測試、回滾、聯絡人，語氣中性

OpenClaw 重度倉庫中 AGENTS.md 的建議骨架

使用穩定標題，便於人與模型檢索。開頭一段寫使命，再明列非目標——哪些操作須有人類核可（上線釋出、鑰匙圈寫入、刪除非相關 lane 的 DerivedData 等）。寫出權威測試入口（xcodebuild test 的 scheme、SwiftPM 選擇、lint 封裝）以及非互動 shell 必備的環境變數。結尾寫升級鏈：企業 IM 頻道、值班表、以及租賃機擷取網關日誌的指令。

• 使命與範圍 — 產品語境、釋出節奏、支援分支。
• 目錄地圖 — 哪些是產生物、哪些是密鑰模板、CI 檢出落在何處。
• 驗證 — 證明變更安全的最小指令集合。
• 回滾 — Git 回退策略及需清理的主機快取。

權杖與篇幅：正文要薄，技能要厚

過大的 Markdown 會與檔案工具取回的程式片段爭搶上下文。優先短段落、連結表與穩定錨點。把長鏈路（標籤、公證 stapling、多區域釋出）遷入技能，由網關按需載入。引用技能時寫明相對路徑與觸發條件（例如「僅在 main CI 全綠後使用」）。每季審視篇幅：若超過約兩頁列印紙，依有界脈絡拆分（iOS 應用 vs 後端服務），並保留頂層索引列出子說明。

Git 審查、標籤與主機釋出紀律

因 AGENTS.md 會影響模型行為，拉取請求應同時由領域工程師與自動化負責人審查。對說明性重大變更打 Git 標籤，並在釋出說明鏡像，便於租賃機將異常行為對應到已知文件版本。避免僅在 SSH 直接改檔而不立即提交——工作區與 origin/main 漂移是「助理依舊檔執行」的常見根因。若調整 agents.json，盡量與 AGENTS.md 同 diff，以便一次審閱策略動作。

無頭租用 Mac：shell、編輯器與符號連結

SSH 工作階段常用 bash／zsh，其 PATH 可能與圖形工作階段不同。在 AGENTS.md 寫明所假設的 profile，並以與 launchd 相同的封裝腳本先行驗證，再讓助理呼叫工具。單體倉庫中的符號連結可能讓模型誤判已越出白名單根；敘述需與白名單文章中的解析規則一致。遠端編輯器偶發自動儲存外掛會產生暫存檔——列出忽略模式，避免模型把它們當成產品程式碼。

決策矩陣：改 AGENTS.md、改 agents.json 還是新建技能

訊號	傾向 AGENTS.md	傾向 agents.json	傾向新技能
變更偏敘述或教學	是——使命、警示、連結	否——避免在 JSON 堆散文	僅當流程很長
變更調整工具允許／拒絕	先寫清理由註腳，再改 JSON	是——機器強制執行	可在技能附輔助說明
變更增加多步 shell 編排	從短文連到技能路徑	少見——保持 JSON 宣告式	是——保持 AGENTS.md 可讀
變更是緊急熱修	事故後再更新文件	優先特性開關或路由切換	將覆盤錨點寫回此處

在租用構建機上導入 AGENTS.md 的九步落地

1. 依 2026-05-11 工作區文章核對白名單根；先消除路徑不一致再寫 prose。
2. 在特性分支起草 AGENTS.md；同步 iOS、後端與安全利害關係人。
3. 為每個 agents.json 畫像映射必讀章節；從正文刪除重複工具表。
4. 任何超過十二步的流程提取為技能，並以穩定相對路徑連結。
5. 以與生產一致的 Node 大版本在本機跑檢查（參見 onboard 指南）。
6. 合併至 main；打 policy/agents-md-YYYYMMDD 標籤便於追溯。
7. 在租賃機拉取；校驗檔案雜湊與 Git 一致。
8. 僅當 JSON 或環境變數變更時才重啟網關；否則遵循你所用建置對檔案熱讀的行為。
9. 記錄前後指標：拒絕的工具呼叫、平均工作階段長度、人工覆寫比例。

常見問題

問題	實務答覆（2026-05-15）
AGENTS.md 是否應寫入 API 金鑰？	否——只寫保管庫名或環境變數鍵；實際值放在密封檔或鑰匙圈，參見密鑰相關文章。
可否維護多語言 AGENTS.md？	僅當各版本策略嚴格同步；否則選定一種 canonical 語言，其餘只翻譯連結而非規則。
多久審閱一次 AGENTS.md？	至少每季及重大 Xcode 或 OpenClaw 升級後；可視為 SLO 儀表板的伴侶文件。

為何 Mac mini M4 租用有利於 AGENTS.md 迭代

高速 NVMe 與統一記憶體讓多份智能體狀態樹、並行 Git 檢出以及「Markdown＋技能」大包同時在線的成本很低，便於在預發租賃機上演練文件再切生產流量。區域與規格對比見 定價；在擴大工具範圍前，請先讓團隊閱讀 SSH 與選用 VNC 指南。