Skip to content

repo-map.md

Latest commit

 

History

History
226 lines (175 loc) · 9.53 KB

repo-map.md

File metadata and controls

226 lines (175 loc) · 9.53 KB

Repo map (where to look in code)

Table of contents (Explain OpenClaw)

This is a "practical navigation guide" for new contributors/readers.

Tip: don't start by reading everything. Start from the Gateway and follow the path of one message.

Top-level directories

Directory Purpose
src/ TypeScript source (~50 subdirectories)
docs/ Canonical documentation (source of truth)
extensions/ Plugins (workspace packages)
apps/ macOS/iOS/Android apps
packages/ Shared workspace packages
ui/ Web UI / dashboard
skills/ Skill definitions
scripts/ Build, release, and utility scripts
test/ Integration / E2E tests
Swabble/ Swabble integration
exports/ Public API exports
vendor/ Vendored third-party code
patches/ Patch files for dependencies
git-hooks/ Git hook scripts
assets/ Static assets (images, icons)

Key entrypoints

CLI

  • src/entry.ts — CLI entry (spawns/sets env, then loads src/cli/run-main.ts)
  • src/cli/ — CLI command definitions
  • src/commands/ — command implementations (~352 files)

Gateway

  • src/gateway/server.impl.ts — Gateway startup, config validation/migration, runtime wiring
  • src/gateway/server-ws-runtime.ts (and siblings) — WS server + RPC handler plumbing
  • docs/gateway/index.md — runbook that matches how it operates in prod

Channels

  • src/channels/ — shared channel logic (identities, allowlists, gating, registry)
  • Per-channel folders with full adapters now live under extensions/: extensions/telegram/, extensions/discord/, extensions/slack/, extensions/signal/, extensions/imessage/, extensions/whatsapp/, extensions/feishu/, extensions/line/, plus legacy src/line/, src/whatsapp/ (still in src/)
  • Additional extension channels: extensions/googlechat/, extensions/msteams/, extensions/matrix/, extensions/zalo/, extensions/zalouser/, extensions/irc/, extensions/nostr/, extensions/tlon/, extensions/twitch/, extensions/mattermost/, extensions/nextcloud-talk/, extensions/synology-chat/
  • docs/channels/ — channel documentation (29 files including pairing, routing, groups)

Agent turns

  • src/auto-reply/ — reply pipeline
  • src/auto-reply/reply/agent-runner.ts — core agent-turn orchestrator
  • src/agents/ — agent framework (~1005 files, 12 subdirectories): tools, sandbox, auth profiles, skills, multi-agent

Routing

  • src/routing/ — dedicated routing module: session-key.ts, resolve-route.ts, bindings.ts

Security

  • src/security/ — security-related logic (audits, policy, external content wrapping)
  • docs/gateway/security/index.md — operator-facing threat model + checklist

Major src/ subdirectories

The src/ directory contains ~50 subdirectories. Key ones beyond the entrypoints above:

Directory Files (approx.) Purpose
src/agents/ ~1005 Agent framework, tools, sandbox, auth profiles, skills
src/gateway/ ~410 Gateway server, WS runtime, RPC handlers, config validation
src/auto-reply/ ~355 Reply pipeline, agent turn orchestration
src/cli/ ~331 CLI command definitions and parsing
src/commands/ ~429 CLI command implementations
src/infra/ ~538 Infrastructure: networking, SSRF guards, exec safety, archiving
src/config/ ~266 Configuration schema, types, validation, migrations
extensions/browser/src/browser/ ~96 Browser automation (CDP/Playwright) — moved from src/browser/ in Mar 27 sync 3
src/channels/ ~191 Shared channel logic, identities, allowlists, registry
src/memory/ ~106 Memory/context management, QMD
src/secrets/ ~53 Secret reference resolution, env substitution, audit
src/cron/ ~118 Cron job scheduling
src/plugins/ ~245 Plugin runtime and loading
src/media-understanding/ ~56 Image/audio/video understanding via AI
src/tui/ ~48 Terminal UI
src/daemon/ ~57 Cross-platform Gateway service lifecycle (systemd, launchd, schtasks)
src/hooks/ — Lifecycle hooks system
src/media/ — Media handling (upload, download, conversion)
src/plugin-sdk/ — Plugin SDK for extension authors
src/routing/ — Message routing, session key derivation
src/sessions/ — Session management and compaction
src/tts/ — Text-to-speech
src/web-search/ — Web search integration and retrieval
src/wizard/ — Setup wizard
src/logging/ — Logging, redaction
src/link-understanding/ — URL preview / link understanding
src/node-host/ — Node.js host for sandboxed execution
src/pairing/ — Device pairing flow
src/process/ — Process management
src/terminal/ — Terminal integration
src/types/ — Shared TypeScript types
src/utils/ — General utilities
src/shared/ — Shared cross-module code
src/acp/ — ACP (Agent Communication Protocol)
src/canvas-host/ — Canvas/drawing host
src/compat/ — Compatibility layers
src/context-engine/ — Context management and orchestration
src/docs/ — In-app documentation helpers
src/markdown/ — Markdown processing
src/scripts/ — Source-level scripts
src/test-helpers/ — Test helper utilities
src/test-utils/ — Test utility functions

Useful ripgrep searches

From repo root:

  • Find where the Gateway is started:

    • search: startGatewayServer
    • file: src/gateway/server.impl.ts

  • Find security audit logic:

    • search: security audit
    • docs: docs/gateway/security/index.md, CLI docs in docs/cli/security.md

  • Find pairing:

    • search: pairing in src/pairing/ and docs/channels/pairing.md

  • Find a specific channel's allowlist behavior:

    • search allowFrom or dmPolicy in channel config types (src/config/types.*.ts — 30 files) and channel runtime

  • Find ChatType / DM policy enum:

    • search: ChatType — used across channel adapters for group vs DM routing

  • Find text sanitization:

    • search: sanitizeUserFacingText — used in reply normalization and agent tools

  • Find memory search logic:

    • search: memorySearch — in src/config/ and src/memory/

How to "trace one message"

  1. Pick a channel (e.g., Telegram).
  2. Find its monitor/adapter in extensions/telegram/.
  3. Follow where it emits a normalized event into shared channel/routing logic.
  4. The src/routing/ module resolves the route and derives a session key (session-key.ts, resolve-route.ts).
  5. src/hooks/ may fire at pipeline stages (pre-reply, post-reply, etc.).
  6. Track how the Gateway selects a session key.
  7. Jump into src/auto-reply/reply/agent-runner.ts to see how the agent turn is run.
  8. For multi-agent flows, src/agents/ orchestrates tool use, sub-agents, and sandbox interactions.
  9. Track how the response is chunked/sent back.

Docs you should keep open while reading code

Documentation Coverage

This section tracks how well the explain-clawdbot/ documentation covers the codebase. Snapshot verified on 2026-03-26.

Coverage by Area

Area Files Last Verified Coverage Notes
CLI Commands 41 top-level commands (40 non-legacy) 2026-03-15 ✅ Complete 01-plain-english/cli-commands.md
Gateway Config 31 root + 14 gateway fields 2026-03-15 ✅ Complete 99-reference/commands-and-troubleshooting.md
Security 15 docs + 105 hardening logs + 261 PR refs + 95 issue refs 2026-03-15 ✅ Complete 08-security-analysis/
Architecture Core paths, extensions/ channel layout 2026-03-15 ✅ Complete 02-technical/architecture.md
Deployment 4 runbooks 2026-03-15 ✅ Complete 03-deploy/
Privacy/Safety 4 guides 2026-03-15 ✅ Complete 04-privacy-safety/

Known Gaps

Gap Impact Priority
Browser automation (CDP) Medium Low (security-irrelevant)
Plugin SDK Low Low
TUI internals Low Low
Provider integrations Medium Medium (may have security implications)

Verification Schedule

Skill Frequency Scope
doc-health-check Weekly Single-file drift audit (report-only)
align-docs-upstream As needed Apply targeted doc fixes after drift is found