Skip to content

README.zh-CN.md

Latest commit

 

History

History
216 lines (143 loc) · 5.22 KB

README.zh-CN.md

File metadata and controls

216 lines (143 loc) · 5.22 KB

DockerClaw

面向 OpenClaw 的系统层级承载框架（OS harness）。

English

LGPL-3.0

Public alpha · framework-first · welcome module contributors

概述

DockerClaw 的存在，是因为 OpenClaw 很强于 agent runtime，但并不擅长 system composition。

OpenClaw 提供了 tools、sessions、prompts、skills 和 browser control；但它并没有提供一套足够严格的机制，去管理 agent 周围的系统环境：包安装、挂载、启动钩子、权限、语言环境、平台兼容性，以及不同 agent 之间的系统差异。

DockerClaw 正是为了解决这一层问题。

它把系统能力抽象成显式模块，把模块组合结果固化为可校验的 lock，再由这些 lock 去驱动 build、compose 和 runtime 行为。

为什么需要 DockerClaw

如果没有系统层，OpenClaw 环境很容易逐步漂移。

  • 包安装散落到不同 Dockerfile 中
  • runtime 逻辑泄漏到启动脚本中
  • agent 间差异越来越难理解
  • 平台假设长期隐式存在
  • 安全边界越来越脆弱

DockerClaw 的方法是把这些问题显式化。

  • module 声明 capability
  • resources 声明 ownership
  • lock 声明最终解析结果
  • validator 保护结构与兼容性
  • generator 生成 build/runtime 产物

最终得到的是一套更安全、更可复制、更适合快速部署的 OpenClaw 系统。

项目状态

DockerClaw 当前处于 public alpha 阶段。

它的架构方向已经清晰且可用，但模块生态、target 支持矩阵以及生成式 runtime 管线仍在持续扩展。

如果你希望参与塑造这套系统本身，现在正是最好的阶段。

设计目标

  • 用显式系统组合替代隐式环境搭建
  • 用 target-aware compatibility 替代口头约定
  • 用生成产物替代手写漂移
  • 在运行前完成强校验
  • 在扩展模块时保持整体清晰度

核心概念

OpenClaw 与 DockerClaw

  • OpenClaw 负责 agent runtime
  • DockerClaw 负责系统层组合

Modules

Module 是平台具体化的系统实现单元。

每个模块定义：

  • module.json - 身份与兼容性
  • resources.json - 资源占用与归属
  • runtime.json - build/runtime 行为
  • instructions.md - 人与 AI agent 的操作说明

Locks

每个 agent 最终都会解析成一个 modules.lock.json。

它记录：

  • 启用的模块
  • target platform 上下文
  • 解析后的资源归属
  • 合并后的 runtime 环境
  • bootstrap 顺序

Targets

Module 默认不视为跨平台通用。

兼容性必须显式声明：

  • OS family
  • base Dockerfile family
  • distro / image family
  • version ranges

当前模块

  • google-drive-mount
  • xfce-desktop
  • locale-pack

一起构建模块生态

DockerClaw 不只是一个框架，也是一份邀请。

如果 OpenClaw 定义了 agent runtime，那么 DockerClaw 想定义支撑这些 agent 的系统环境：可移植、可组合、可验证、可部署。

我们希望开发者一起贡献开放模块，例如：

  • 操作系统集成
  • 桌面与浏览器环境
  • 存储与挂载能力
  • locale 与平台包
  • 校验、生成与部署工作流

如果你想参与，请先看：

  • CONTRIBUTING.md
  • dev-rules/module-development.md
  • modules/template-module/

工具链

校验模块契约：

python3 scripts/validate-modules.py

生成 agent lock：

python3 scripts/generate-modules-lock.py <agent-name> <module> [<module> ...]

校验 agent lock：

python3 scripts/validate-agent.py <agent-name|path-to-modules.lock.json>

从 lock 生成 Dockerfile：

python3 scripts/generate-dockerfile.py <agent-name|path-to-modules.lock.json> [output-path]

从 lock 生成 compose 片段：

python3 scripts/generate-compose-fragment.py <agent-name|path-to-modules.lock.json> [output-path]

聚合 compose 片段：

python3 scripts/generate-compose.py <agent> [<agent> ...]

准备单个 agent：

python3 scripts/prepare-agent.py <agent-name> <module> [<module> ...]

按现有 locks 准备整套 stack：

python3 scripts/prepare-stack.py <agent> [<agent> ...]

仓库结构

  • dockerclaw-framework.md - 框架与架构模型
  • dev-rules/ - 面向人类与 AI agent 的开发规则
  • modules/ - 可复用的 DockerClaw 模块
  • dockerfiles/ - Dockerfile 家族，如 current/minimum 基底
  • scripts/ - 校验器、生成器、编排辅助脚本
  • agents/ - 本地机器状态，默认不进 git

当前状态

DockerClaw 仍是一个持续演进中的框架，而不是一个封闭成品。

当前已经比较扎实的部分：

  • 显式模块契约
  • target-aware compatibility 规则
  • lock 驱动组合
  • Dockerfile / compose 生成产物
  • 基于 lock 的 runtime 模块调度

建议继续阅读

  • 架构文档：dockerclaw-framework.md
  • 模块开发规则：dev-rules/module-development.md
  • lock 示例：modules.lock.example.json
  • 贡献指南：CONTRIBUTING.md
  • 安全说明：SECURITY.md
  • Roadmap：roadmap/README.md

方法论

OpenClaw 继续专注 runtime。

DockerClaw 的价值，是把 runtime 之外的系统层做得更安全、更清晰、更容易部署。