close
OpenClaw Internals
  • English

      • Markdown-as-Config

      One-line summary

      OpenClaw uses Markdown files with YAML frontmatter as the primary configuration and data format, instead of JSON/YAML config files or databases.

      Where it appears

      ModuleHow it uses this pattern
      Skills SystemEach skill is a SKILL.md with YAML frontmatter for metadata and Markdown body for instructions
      MemoryAgent memory is stored as plain Markdown files under ~/clawd/
      Agent ConfigurationAgent behavior is partially defined through Markdown instruction files
      Session NotesDurable notes written by the agent during /compact are Markdown

      How it works

      Instead of structured config files (JSON, YAML, TOML) or a database, OpenClaw stores configuration and data as Markdown files. Metadata goes in YAML frontmatter (--- delimited block at the top), content goes in the Markdown body.

      ---
name: my-skill
description: Does a thing with an API
metadata:
  openclaw:
    requires:
      env:
        - MY_API_KEY
---

# my-skill

Instructions for the agent on how to use this skill...

      Why OpenClaw uses it

      1. Human-readable and human-editable: No special tools needed. Any text editor works.
      2. AI-readable: LLMs can parse Markdown natively. No serialization/deserialization needed for the agent to understand skill instructions.
      3. Git-friendly: Markdown diffs are clean and reviewable. The entire workspace can be version-controlled.
      4. Tool-agnostic: Works with Obsidian, VS Code, Vim, or any Markdown-aware tool.

      Implications for contributors

      • When adding new features that need configuration, consider whether Markdown-with-frontmatter is appropriate before reaching for JSON.
      • Skill instructions are injected directly into the agent's system prompt. What you write in SKILL.md is literally what the LLM sees. Write for the model, not just for humans.
      • Memory files are append-friendly. The system assumes it can write new Markdown files without coordinating with existing ones.
      • local-first-persistence (planned)