openclaw-notes/AGENTS.md

AGENTS.md

This is a personal Obsidian vault of study notes analyzing the OpenClaw (and occasionally OpenCode) source code. There is no build/test/lint/CI — it's markdown only. Notes are written in Chinese (simplified); match that when adding or editing content.

Repo layout — two distinct note types, don't mix them up

• Root *.md — deep technical/architecture notes (研究笔记): source-cited, precise, written for the author's own understanding. Cite exact file paths and line refs from the source repo.
• blog/*.md — reader-facing "101" explainer articles (科普向), derived from the same research but rewritten for an outside audience (problem → intuition → source-backed example). Don't add deep-dive content here; put it in a root note and link to it instead (see cross-links at the bottom of blog/skills-101.md / blog/rag-101.md for the pattern).
• Each of README.md (root) and blog/README.md is a manual index listing every note with a 2-3 line summary. When adding a new note file, add an entry to the matching README — this is easy to forget (two existing notes, agent-loop-notes.md and opencode-plan-mode.md, are currently missing from the root index).
• .obsidian/ is Obsidian's vault config (workspace layout, plugins) — don't hand-edit workspace.json; it's UI state, not content.

Source of truth lives outside this repo

This folder is a nested git repo (own history/remotes) living inside a checkout of the OpenClaw source at the parent directory (/Users/clz/Code/openclaw, one level up from here). That parent repo has its own AGENTS.md/docs/ — notes here are written by reading that source, not by re-deriving architecture from prose.

Some notes (e.g. opencode-plan-mode.md) instead study a sibling repo, referenced in the note as ../opencode (i.e. /Users/clz/Code/opencode relative to this vault's parent). If a note cites a sibling repo, verify claims against that repo's actual source before editing/extending the note — don't trust the note's paraphrase alone.

When writing or updating a note:

• State which source repo/version the note is based on (existing notes open with a blockquote like > 基于 2026.6.2 版本源码，关键文件：... or > 基于 sibling 仓库 ../opencode 源码实读) — follow that convention.
• Prefer citing concrete file:line references over paraphrased claims.

Git remotes

Two remotes are configured and both are pushed to: origin (GitHub, FadingLight9291117/openclaw-notes) and gitea (private instance at git.fadinglight.cn). Don't assume only one remote — push to both if asked to publish, or ask which one if unclear.