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 回退策略及需清理的主机缓存。

Token 与篇幅：正文要薄，技能要厚

过大的 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 指南。