OpenClaw 学习系列之二：项目地图

项目地图

打开代码前先看这份地图，快速定位你想找的东西。

顶层目录

复制代码

openclaw/
├── src/                 # 核心源码（TypeScript ESM）
├── extensions/          # 渠道和功能插件（独立 npm 包）
├── apps/                # 原生应用（iOS / Android / macOS）
├── ui/                  # Web 前端
├── packages/            # 工作区共享包
├── scripts/             # 构建和运维脚本
├── docs/                # 文档（Mintlify）
├── test/                # 测试工具
└── dist/                # 编译输出

src/ 核心结构

按功能分组，列出你最可能需要看的目录：

消息入口和路由

目录	作用	关键文件
`src/gateway/`	Gateway 服务器主体	`server.impl.ts` (主入口), `server-channels.ts`
`src/gateway/server-methods/`	RPC 方法处理器	`chat.ts`, `send.ts`, `types.ts`
`src/routing/`	消息路由决策	`resolve-route.ts`, `session-key.ts`
`src/channels/`	渠道抽象与注册	`plugins/types.plugin.ts`, `plugins/types.adapters.ts`
`src/auto-reply/`	自动回复分发	`dispatch.ts`, `reply/`

Agent 和 AI 调用

目录	作用	关键文件
`src/agents/`	Agent 运行时	`pi-tools.ts`, `context.ts`
`src/agents/pi-embedded-runner/`	嵌入式 Agent 执行器	`run.ts`

配置和状态

目录	作用	关键文件
`src/config/`	配置加载与校验	`types.ts` (类型导出), `types.base.ts`, `io.ts`
`src/sessions/`	会话持久化	`session-key-utils.ts`
`src/memory/`	长期记忆 (SQLite + 向量)

基础设施

目录	作用	关键文件
`src/cli/`	CLI 入口和命令路由	`entry.ts`, `run-main.ts`, `deps.ts`
`src/commands/`	各 CLI 子命令实现
`src/plugins/`	插件注册表和运行时	`registry.ts`, `types.ts`
`src/plugin-sdk/`	插件开发公共 SDK
`src/infra/`	底层工具（日志、错误、进程）	`agent-events.ts`
`src/shared/`	共享工具函数	`lazy-runtime.ts`
`src/media/`	媒体处理管道

extensions/ 插件目录

每个插件是独立的 npm 包，有自己的 package.json 和 openclaw.plugin.json。

常见渠道插件：feishu、matrix、msteams、bluebubbles、zalo、voice-call 等。

核心渠道（src/ 内置）：telegram、discord、slack、signal、imessage、web（WhatsApp）。

运行时数据位置

数据	路径	格式
配置文件	`~/.openclaw/openclaw.json`	JSON5
会话记录	`~/.openclaw/sessions/`	JSONL (追加写)
记忆数据库	`~/.openclaw/memory/`	SQLite + 向量嵌入
凭据	`~/.openclaw/credentials/`	各类 token (权限 0600)
Agent 日志	`~/.openclaw/agents/<id>/sessions/*.jsonl`	JSONL

开发命令速查

bash 复制代码

pnpm install          # 安装依赖
pnpm build            # 类型检查 + 编译
pnpm tsgo             # 仅类型检查
pnpm check            # lint + format 检查
pnpm format:fix       # 自动格式化
pnpm test             # 运行测试 (vitest)
pnpm test -- src/routing/resolve-route.test.ts  # 运行单个测试
pnpm dev              # 开发模式运行 CLI
pnpm openclaw ...     # 以 dev 模式执行 CLI 命令