第十一章：源码结构、开发调试与插件开发

开发者可通过源码研究 Gateway、通道、工具、插件和 UI。官方推荐源码 checkout 使用 pnpm workspace。

11.1 源码开发流程

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm openclaw setup
pnpm ui:build
pnpm gateway:watch

需要构建 dist：

pnpm build
pnpm ui:build

pnpm openclaw ... 通常通过 TypeScript 直接运行；pnpm gateway:watch 是开发循环；修改 UI 后需要重新构建或使用 UI dev 命令。

11.2 仓库结构

重要目录：docs/ 文档，extensions/ 插件与通道，apps/ 伴随应用，skills/ 内置技能，scripts/ 构建与发布脚本，config/ 配置资源，deploy/ 部署资源，Dockerfile/docker-compose.yml 容器化，package.json npm 包定义。

11.3 插件能扩展什么

插件可扩展通道、工具、模型 provider、技能、语音、转录、图片/音乐/视频生成、Web fetch/search、诊断和监控。插件通常通过 manifest 声明 contracts，通过 SDK 注册能力，并提供配置 schema。

11.4 通道插件设计

通道插件要处理认证、入站事件、出站能力、稳定发送者 ID、群聊/私聊差异、媒体、去重、重连、健康检查、日志脱敏、配置 schema、DM policy、group policy 和 pairing。难点不是发送一条消息，而是正确融入 Gateway 安全与会话模型。

11.5 工具插件设计

工具要定义名称、描述、输入 schema、输出结构、权限风险、依赖、是否有副作用、是否需要 confirmation 或 dry-run。高风险工具必须有清晰文档，并配合 allow/deny、approval 和沙箱。

11.6 技能随插件分发

插件可附带技能，让 Agent 知道如何使用插件工具。插件技能优先级较低，用户可以用工作区技能覆盖。工具提供能力，技能提供方法，两者配合才能稳定发挥效果。

11.7 配置 schema

良好插件应提供字段类型、默认值、title/description、必填项、枚举、secret 标记和错误提示。Control UI 和 Gateway 校验都依赖 schema。

11.8 调试建议

使用测试 workspace、测试账号和低权限 token；打开 verbose 日志；运行 openclaw doctor；为权限拒绝、token 过期、重连、去重和危险工具写测试；不要把真实 secret 写入测试快照。

11.9 小结

源码开发要围绕 Gateway 模型思考。通道、工具、插件都要接入配置、schema、日志、安全、会话、健康检查和 UI，而不是孤立实现。