2026-05-15 OpenClaw Arbeitsbereich AGENTS.md als Repo-Briefing auf headless gemietetem Apple Silicon Cloud-Mac (HK / JP / KR / SG / US)

Wenn OpenClaw ein ganzes Monorepo lesen kann, ist das höchste Hebel-Dokument oft nicht noch ein JSON-Knopf, sondern ein diszipliniertes AGENTS.md an der Git-Wurzel, das Menschen und Modellen den „Normalzustand“ erklärt. Auf gemieteten Mac mini M4 in Hongkong, Tokio, Seoul, Singapur und den USA teilen sich Hosts häufig xcodebuild-Lanes, Signing-Bäume und Assistenten, die Swift bearbeiten. Dieses 2026-05-15-Playbook ordnet AGENTS.md in den Gesamt-Policy-Stack ein: es bleibt konsistent mit Workspace-Erlaubnislisten und Monorepo-Schutz, ergänzt die Rollentrennung in agents.json und wird gemeinsam mit Onboard, launchd und doctor gepflegt—ohne maschinenlesbare Tool-Listen zeilenweise in Markdown zu spiegeln.

Warum Repo-weites AGENTS.md trotz agents.json

agents.json kodiert Identitäten, Modelle und Tool-Oberflächen; es ist der Vertrag, den das Gateway deterministisch parsen soll. AGENTS.md beantwortet andere Fragen: welches Produkt dieses Repo baut, welche Verzeichnisse tabu sind, welcher Testbefehl maßgeblich ist, wie Rollbacks gestaffelt werden und wen man bei riskanten Edits weckt. Auf geteilten Miet-Buildern macht diese Erzählung die Absicht in Incident-Diffs sichtbar—über Arrays im JSON hinaus. Halten Sie den Text in etwa zwei Minuten Vorlesedauer; lange Abläufe wandern in Skills, während hier Einstiegspfade und Triggerbedingungen stehen.

Policy-Stack: Position von AGENTS.md zu Listen und agents.json

Von oben nach unten: Transport & Kanäle, Gateway-Routing, Workspace-Allowlists, Agent-Runtime-JSON, optionale Skills, zuletzt Repo-Anweisungen. AGENTS.md steht dem sozialen Vertrag des Repos am nächsten—es hebt keine Dateisystem-Policies der Art „default deny“ auf, erklärt aber, warum Wurzeln existieren und welches Verhalten Assistenten dort erwarten. Mehrere Agenten auf einem Host lesen dasselbe Repo; AGENTS.md bleibt persona-neutral, während agents.json Tools eingrenzt.

Schicht	Hauptartefakt	Eigentümer	AGENTS.md soll…
Dateisystem-Schutz	Workspace-Allowlists	Plattform / Security	Wurzeln per Pfad referenzieren, keine konkurrierenden Regeln schreiben
Runtime-Policy	agents.json	Automatisierungsverantwortliche	Profilabsicht erklären und JSON-Pfade in Git verlinken
Prozedurtiefe	Skills / Runbooks	Service-Teams	Stabile Überschriften indexieren, keine mehrseitigen Shell-Skripte einfügen
Mensch+Modell-Kontext	AGENTS.md	Repo-Maintainer	Mission, Tests, Rollback, Kontakte neutral formulieren

Empfohlenes Skelett für stark OpenClaw-lastige Repos

Stabile Überschriften erleichschen Suche für Mensch und Modell. Beginnen Sie mit der Mission, listen Sie Nicht-Ziele explizit—Aktionen, die menschliche Freigabe brauchen (Produktions-Deploys, Schlüsselbund-Schreiben, Löschen fremder DerivedData). Dokumentieren Sie maßgebliche Testeinstiege (xcodebuild test-Schemes, SwiftPM-Auswahl, Lint-Wrapper) und nötige Umgebungsvariablen für nicht-interaktive Shells. Schließen Sie mit Eskalation ab: Slack-Kanal, Bereitschaft, Befehl zum Gateway-Log-Zug auf dem Miet-Host.

• Mission und Umfang — Produktkontext, Release-Takt, unterstützte Branches.
• Verzeichniskarte — generierte Artefakte, Secret-Vorlagen, CI-Checkout-Pfade.
• Verifikation — kleinste sichere Kommandokette.
• Rollback — Git-Revert-Strategie plus Host-Caches zum Leeren.

Token-Budget: AGENTS.md dünn, Skills dick

Große Markdown-Blöcke konkurrieren mit Code-Snippets aus Datei-Tools. Kurze Absätze, Linktabellen und stabile Anker bevorzugen. Lange Ketten (Release-Tagging, Notarize/Stapling, Multi-Region-Rollout) in Skills auslagern, die das Gateway bei Bedarf lädt. Bei Skill-Referenzen relativen Pfad und Trigger angeben („nach grüner CI auf main“). Quartalsweise Länge prüfen; über etwa zwei Druckseiten hinaus nach bounded context (iOS-App vs. Backend) splitten und ein Index-Dokument oben halten.

Git-Review, Tags und Host-Rollout-Disziplin

Weil AGENTS.md Modellverhalten beeinflusst, brauchen Pull-Requests Reviews von Domäneningenieur und Automatisierungsowner. Bei inhaltlich großen Änderungen Git-Tags setzen und in Release-Notizen spiegeln, damit Miet-Host-Anomalien einer bekannten Dokumentversion zugeordnet werden können. Direktes SSH-Editieren ohne sofortigen Commit vermeiden—Drift zwischen Arbeitsbaum und origin/main ist ein häufiger Grund, warum Assistenten alte Texte befolgen. agents.json-Änderungen möglichst im selben Diff wie AGENTS.md führen.

Headless-Miet-Mac: Shells, Editoren, Symlinks

SSH-Sitzungen nutzen oft bash/zsh mit anderem PATH als die GUI. Profilannahmen in AGENTS.md dokumentieren und mit denselben launchd-Wrappers verifizieren, bevor Toolaufrufe delegiert werden. Symlinks im Monorepo können außerhalb erlaubter Wurzeln suggerieren—Erzählung an Auflösungsregeln aus Allowlist-Artikeln angleichen. Remote-Editor-Autosave erzeugt Temporärdateien; Ignore-Muster nennen, damit sie nicht als Produktcode gelesen werden.

Entscheidungsmatrix: AGENTS.md vs. agents.json vs. neuer Skill

Signal	AGENTS.md bevorzugen	agents.json bevorzugen	neuen Skill bevorzugen
Änderung erzählerisch oder didaktisch	Ja—Mission, Warnungen, Links	Nein—keine Prosa im JSON	nur bei langen Prozeduren
Tool-Allow/Deny ändern	Grund in Fußnote, dann JSON	Ja—maschinell erzwungen	Hilfstext im Skill möglich
Mehrstufige Shell-Choreographie	Kurzlink zum Skill-Pfad	selten—JSON deklarativ halten	Ja—Lesbarkeit von AGENTS.md wahren
Notfall-Hotfix	Dokument nach Vorfall aktualisieren	Zuerst Feature-Flags oder Router	Postmortem-Anker hier

Neun Schritte zur Einführung von AGENTS.md auf einem Miet-Builder

1. Erlaubte Wurzeln mit dem Workspace-Artikel vom 2026-05-11 prüfen, bevor Prosa entsteht.
2. AGENTS.md in einem Feature-Branch entwerfen; iOS-, Backend- und Security-Stakeholder einbeziehen.
3. Jedes agents.json-Profil auf Pflichtabschnitte mappen; doppelte Tooltabellen aus dem Fließtext entfernen.
4. Abläufe mit mehr als zwölf Schritten in Skills auslagern und stabil relativ verlinken.
5. Lokale Checks mit derselben Node-Major wie Produktion (siehe Onboard-Artikel).
6. Nach main mergen; Tag policy/agents-md-YYYYMMDD für Nachverfolgbarkeit.
7. Auf dem Miet-Host pullen und Hashes mit Git abgleichen.
8. Gateways nur bei JSON- oder Umgebungsänderungen neu starten; sonst Datei-Reload-Semantik des Builds befolgen.
9. Vorher/Nachher-Metriken: abgelehnte Toolversuche, mittlere Sitzungsdauer, menschliche Override-Rate.

FAQ

Frage	Praktische Antwort (2026-05-15)
API-Schlüssel in AGENTS.md?	Nein—nur Tresor-Namen oder Variablenkeys; Werte in versiegelten Dateien oder Schlüsselbund.
Mehrsprachige AGENTS.md-Dateien?	Nur bei strikt synchroner Policy; sonst eine kanonische Sprache, übersetzte Links statt Regeln.
Wie oft reviewen?	Mindestens quartalsweise und nach großen Xcode- oder OpenClaw-Upgrades; als Begleiter zu SLO-Dashboards behandeln.

Warum Mac mini M4-Mieten AGENTS.md-Iterationen erleichtert

Schnelles NVMe und vereinheitlichter Speicher halten mehrere Agentenstatusbäume, parallele Git-Checkouts und große Markdown+Skill-Bündel gleichzeitig billig—ideal, um Dokumentänderungen auf einer Staging-Lease vor Produktionsverkehr zu proben. Regionen auf der Seite Preise vergleichen und vor Tool-Erweiterung die SSH- und optionalen VNC-Leitfäden im Team lesen.