https://github.com/hrygo/openclaw-devkit
OpenClaw DevKit - Containerized development toolkit for OpenClaw multi-channel AI productivity platform. Integrated development, debugging, and testing toolchain.
https://github.com/hrygo/openclaw-devkit
ai automation claude claude-code container devcontainer development-environment development-tools devops docker docker-compose productivity toolkit
Last synced: 6 days ago
JSON representation
OpenClaw DevKit - Containerized development toolkit for OpenClaw multi-channel AI productivity platform. Integrated development, debugging, and testing toolchain.
- Host: GitHub
- URL: https://github.com/hrygo/openclaw-devkit
- Owner: hrygo
- Created: 2026-02-19T13:50:02.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-03-29T14:16:21.000Z (10 days ago)
- Last Synced: 2026-03-29T17:32:25.157Z (10 days ago)
- Topics: ai, automation, claude, claude-code, container, devcontainer, development-environment, development-tools, devops, docker, docker-compose, productivity, toolkit
- Language: Shell
- Homepage:
- Size: 3.52 MB
- Stars: 9
- Watchers: 0
- Forks: 10
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# 🛠️ OpenClaw 开发工具箱 (OpenClaw DevKit)
English | 简体中文
---
**OpenClaw 开发工具箱**是为 [OpenClaw](https://github.com/openclaw/openclaw) 量身定制的容器化开发环境。一键启动，秒级进入 AI 辅助编程与自动化工作状态。
---
## ✨ 核心特性
- 📦 **一键就绪**：基于 Docker Compose，屏蔽繁琐依赖
- 🧩 **1+3 阶梯架构**：采用高效的「1个基座 + 3类堆栈」设计，极致 DRY
- 🧠 **AI 原生集成**：内置 Claude Code、OpenCode、Pi-Mono
- 🔧 **开箱即用**：预配置开发环境，无需手动搭建
- 🚀 **快速启动**：一键部署，分秒间启动完整开发栈
- 🔒 **安全隔离**：容器化运行，环境隔离安全可控
- 💾 **数据持久化**：会话、配置自动保存，重启不丢失
- 🩹 **自愈引擎**：Entrypoint 自动修复路径泄露、清理失效 Secret，确保 100% 成功启动
---
## 前置条件
### 通用要求
- **Docker**: V2 (Docker Desktop for macOS/Windows, Docker Engine for Linux)
- **Docker Compose**: V2 (内置于 Docker Desktop)
- **Make**: macOS/Linux 自带，Windows 用户安装 [Git Bash](https://git-scm.com/download/win) 即可完美适配（内置 `Makefile` 已针对 Git Bash 进行了路径转换优化）。
### Windows 用户特殊要求
| 组件 | 要求 | 说明 |
| :--- | :--- | :--- |
| **操作系统** | Windows 10 21H2+ 或 Windows 11 | |
| **后端引擎** | WSL2 (推荐) 或 Hyper-V | [安装指南](https://docs.microsoft.com/zh-cn/windows/wsl/install) |
| **内存** | 推荐 8GB+ | Docker Desktop 最低 4GB |
| **虚拟化** | 需在 BIOS/UEFI 中启用 | Intel VT-x / AMD-V |
> [!TIP]
> Windows 推荐使用 **Docker Desktop** 基于 WSL2 后端运行（性能更佳）。若使用 WSL2，需在 PowerShell 中执行以下命令启用：
> ```powershell
> wsl --install
> ```
> *(注：Windows 10/11 专业版及更高版本用户也可选择使用传统的 Hyper-V 后端，此时无需安装 WSL2。)*
---
## 🚀 快速开始
### 1. 标准安装 ⭐（推荐 - 极速模式）
适用于大多数用户，直接从 GitHub 注册表拉取经过优化的预构建镜像，**无需本地编译**。
```bash
# 1. 下载并安装 (极速模式)
git clone https://github.com/hrygo/openclaw-devkit.git && cd openclaw-devkit
make install
# 2. 交互式配置 (初次使用)
make onboard
# 3. 启动服务
make up
# 4. 一键直达仪表盘 (自动带 token)
make dashboard
# 5. 如显示 "pairing required"，批准配对
make approve
```
> [!NOTE]
> `make install` 会自动完成：创建数据目录、生成 `.env` 配置、同步镜像以及修复宿主机权限。
> **注意**：`make install` 仅进行安装与准备，**不会自动启动服务**。请在安装完成后根据流程执行 `make onboard` 和 `make up`。
### 首次访问 UI 认证流程
OpenClaw 使用 token 认证保护 Gateway。首次访问 UI 时：
| 步骤 | 命令 | 说明 |
| :--- | :--- | :--- |
| 1 | `make dashboard` | 生成带 token 的直通链接，自动打开浏览器 |
| 2 | 刷新页面 | 如显示 "pairing required"，继续下一步 |
| 3 | `make approve` | 批准配对请求 |
| 4 | 刷新页面 | 完成认证，正常使用 |
### 版本选择
根据您的开发需求选择合适的版本：
| 版本 | 镜像标签 | 适用场景 | 核心工具 |
| :--- | :--- | :--- | :--- |
| **标准版** | `latest` | 通用 Web 开发 | Node.js 22, Bun, Claude Code, Playwright, Python 3 |
| **Go 版** | `go` | Go 后端开发 | 标准版 + Go 1.26, golangci-lint, gopls, dlv |
| **Java 版** | `java` | Java 后端开发 | 标准版 + JDK 21, Gradle, Maven |
| **Office 版** | `office` | 文档处理/RAG | 标准版 + LibreOffice, pandoc, LaTeX, Docling, Marker-PDF |
```bash
# 安装指定版本
make install go
make install java
make install office
```
首次安装后修改 `.env` 中的 `OPENCLAW_IMAGE`，然后执行 `make upgrade` 切换版本。
### 日常运维
| 场景 | 命令 |
| :--- | :--- |
| 启动服务 | `make up` |
| 停止服务 | `make down` |
| 重启服务 | `make restart` |
| 查看状态 | `make status` |
| 查看日志 | `make logs` |
| 进入容器 | `make shell` |
| 强制更新镜像 | `make upgrade` |
---
## 🔄 升级指南
### 存量用户升级（重要）
如果您之前使用过 `openclaw` 项目（旧目录名），升级到 `openclaw-devkit` 后可能会看到以下警告：
```
WARN[0000] volume "openclaw-devkit-home" already exists but was created for project "openclaw"
WARN[0000] volume "openclaw-claude-home" already exists but was created for project "openclaw"
```
**这是正常现象，不影响使用**。如需消除警告，执行一次性迁移：
### 跨平台迁移命令
```bash
# 自动备份 → 删除旧卷 → 重建新卷 → 恢复数据
./scripts/migrate-volumes.sh
# 或自动确认模式
./scripts/migrate-volumes.sh -y
# 或使用 Make 命令（自动检测平台）
make migrate-volumes
```
```powershell
# PowerShell 版本
.\scripts\migrate-volumes.ps1
# 或自动确认模式
.\scripts\migrate-volumes.ps1 -AutoConfirm
```
**迁移脚本特性：**
- ✅ 自动检测是否需要迁移
- ✅ 完整备份机制（数据安全）
- ✅ 1-3 分钟完成（取决于数据量）
- ✅ 迁移后警告永久消失
技术细节：为什么会有警告？
Docker Compose 使用项目标签追踪卷的归属。旧项目名 `openclaw` 与新项目名 `openclaw-devkit` 不匹配触发警告。`migrate-volumes.sh` 会重新创建带正确标签的卷。
**安全保证：**
- 备份文件保留在 `/tmp/openclaw-volume-backup-*/`
- 可随时手动恢复
- 迁移失败会中止并提示
### 常规版本升级
```bash
# 检测并拉取最新镜像
make upgrade
# 重启服务以应用更新
make restart
```
---
## ❓ 常见问题
Q: 启动后显示"无法连接"？
确保代理开启「允许局域网」连接，运行 `make test-proxy` 诊断网络。
Q: 如何强制更新镜像到最新版本？
`make install` 默认使用本地缓存。若要检测并更新远程镜像，请运行：
```bash
make upgrade
```
或手动执行 `docker pull ghcr.io/hrygo/openclaw-devkit:latest`。
Q: 如何切换版本？
修改 `.env` 中的 `OPENCLAW_IMAGE`，然后执行 `make upgrade `。
Q: 配置文件在哪？如何从宿主机修改？
DevKit 采用**直接 Bind Mount 共享**设计：
| 宿主机路径 | 容器路径 | 用途 |
|:----------|:--------|:-----|
| `~/.openclaw/` | `/home/node/.openclaw/` | 配置文件，双向实时同步 |
**修改配置**：直接编辑宿主机的 `~/.openclaw/openclaw.json`，无需重启即可热加载。
Q: 宿主机已安装 OpenClaw，冲突怎么办？
容器与宿主机模式会争夺端口 18789。运行 `./docker-setup.sh` 时会自动检测并尝试停止宿主机服务。
若需手动处理：
```bash
# 查看卸载指南
make uninstall-host
# 推荐一键卸载
npx -y openclaw uninstall --all --yes --non-interactive
```
---
## 📚 技术文档
| 文档名称 | 描述 | 关键点 |
| :--- | :--- | :--- |
| [镜像变体指南](./docs/IMAGE_VARIANTS.md) | 详解 1+3 架构与各版本差异 | `latest`, `go`, `java`, `office` 区别 |
| [Docker 工作流](./docs/DOCKER_WORKFLOW.md) | 本地开发与 CI/CD 流程 | `make` 命令、GitHub Actions 逻辑 |
| [快速入门指南](./docs/USER_ONBOARDING.md) | 详细的配置与环境变量说明 | `.env` 配置、Claude API 设置 |
| [飞书配置](./docs/FEISHU_SETUP.md) | 聊天应用与 AI Agent 联动 | 机器人创建、Webhook 配置 |
| [Slack 配置](./docs/SLACK_SETUP_BEGINNER.md) | Slack 接入 OpenClaw | 机器人创建、Socket Mode 配置 |
| [NotebookLM 技能](./docs/NOTEBOOKLM_SKILL.md) | NotebookLM CLI 集成指南 | 播客生成、来源管理、内容导出 |
| [详细参考手册](./docs/REFERENCE.md) | 完整的 Makefile 命令参考 | 进阶运维指令、故障排查 |
**外部资源**：[OpenClaw 官方文档](https://docs.openclaw.ai) | [Claude Code 文档](https://docs.anthropic.com/en/docs/claude-code) | [notebooklm-py GitHub](https://github.com/teng-lin/notebooklm-py)
---
## 📄 许可证
基于 [OpenClaw](https://github.com/openclaw/openclaw) 原始许可。