# JackClaw

**Repository Path**: jackgoogle/JackClaw

## Basic Information

- **Project Name**: JackClaw
- **Description**: JackClaw是一个集成 AI 智能体的全栈开发辅助平台，提供智能对话、项目管理、文件浏览、版本控制、技能管理、记忆系统、Always-On 自动化和路由仪表板等功能。系统采用前后端分离架构，支持 SaaS（多租户）和单租户两种部署模式。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-06-27
- **Last Updated**: 2026-07-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<br />

***

# 📦 安装与快速开始

我们提供了 macOS/Linux 下的一键安装脚本，以及适合开发者的源码启动方式。

### 方式一：一键安装 (推荐, macOS/Linux)

```bash
curl -fsSL https://raw.githubusercontent.com/OpenBMB/HcEngine/main/install.sh | bash
```

该脚本将自动配置 Node.js 24 环境、克隆代码、安装依赖并编译前端。安装完成后，直接运行：

```bash
HcEngine            # 在 http://localhost:3001 启动服务
HcEngine status     # 查看运行状态
```

### 方式二：源码启动 (适合开发者)

1\. 克隆代码与安装依赖

> 本仓库使用 [Git LFS](https://git-lfs.com/) 管理大型媒体文件。克隆前请确保已安装 `git lfs`。
> 如果不需要演示视频/GIF，可在 clone 前加上 `GIT_LFS_SKIP_SMUDGE=1` 跳过下载。

```bash
git clone https://gitee.com/jackgoogle/hc-engine.git
cd HcEngine

corepack enable
corepack prepare pnpm@10.32.1 --activate
pnpm install --frozen-lockfile   # 安装根目录、UI workspace 与本地 file 依赖
```

> 注意：请不要在本仓库执行     `npm install`。\
> HcEngine 是 pnpm workspace 项目，依赖树由根目录的 `pnpm-lock.yaml` 和 `pnpm-workspace.yaml` 管理。
> 如果使用 npm 安装，npm 可能会读取 pnpm 生成的 `node_modules/.pnpm` 虚拟存储结构，并在 Arborist 构建依赖树时出现
> `Cannot read properties of null (reading 'matches')` 之类的错误。
>
> Windows / nvm 用户建议使用 Node.js 24.14.0 或更新版本，例如：
>
> ```powershell
> nvm use 24.14.0
> pnpm install --frozen-lockfile
> ```
>
> 如果已经误执行过 `npm install`，可能会留下半安装状态。可删除本项目内的依赖目录后重新安装：
>
> ```powershell
> Remove-Item -LiteralPath .\node_modules,.\ui\node_modules -Recurse -Force
> nvm use 24.14.0
> pnpm install --frozen-lockfile
> ```

> 如果你在 Windows 上仍然遇到 `Cannot read properties of null (reading 'matches')`，
> 优先检查是否误用了 `npm install`，以及根目录和 `ui` 目录下是否残留旧的 `node_modules`。
> 这类问题通常在切换到 Node.js 24.14.0 以上并重新执行 `pnpm install --frozen-lockfile` 后消失。

2\. 配置模型 Provider

HcEngine 依赖 `~/.hcengine/hcengine.yaml` 进行配置。您可以手动创建、运行启动脚本自动生成，，，或者在启动 Web UI 后直接在设置界面中进行可视化配置，，。
支持 OpenAI、Anthropic、DeepSeek、Qwen、Kimi、MiniMax 等多种协议。

```yaml
schemaVersion: 1
agent:
  model: deepseek/deepseek-v4-pro
model:
  providers:
    deepseek:
      protocol: openai
      url: https://api.deepseek.com/v1
      apiKey: sk-your-api-key
```

3\. 启动服务

```bash
cd ui && pnpm run dev    # 开发模式 (HMR)，访问 http://localhost:5173
# 或
cd ui && pnpm run start  # 生产模式，访问 http://localhost:3001
```

### 方式三：Docker Compose

如果您已安装 Docker，也可以直接使用容器方式启动：

```bash
docker compose up -d
```

***

## 🛠️ 扩展与插件 (Extension Protocol)

HcEngine 采用开放的插件架构，插件代码与开源核心严格隔离。开发者可以通过 `plugin.json` 轻松扩展系统能力：

- MCP Servers  : 原生支持集成 Model Context Protocol 服务器。
- Tools & Skills  : 注册自定义工具，或通过 [ClawHub](https://www.npmjs.com/package/clawhub) 引入社区 Skill。
- Lifecycle Hooks  : 拦截 `PreToolUse`、`UserPromptSubmit` 等关键生命周期。
- Custom Memory  : 允许接入自定义的记忆存储 Provider。

***

## 🙏 致谢

感谢 OpenClaw、Claude Code、Codex、Cursor、Hermes 等 Agent OS 先行者的探索，为这一领域的发展提供了重要启发。

HcEngine 的建设离不开以下优秀开源项目的支持：

- [ClawXRouter](https://github.com/OpenBMB/ClawXRouter) — 智能模型路由
- [ClawXMemory](https://github.com/OpenBMB/ClawXMemory) — Agent 记忆系统
- [Claude Code UI](https://github.com/siteboon/claudecodeui) — Web UI 参考
- [Claude Code Router](https://github.com/musistudio/claude-code-router) — 模型路由参考
- [UltraRAG](https://github.com/OpenBMB/UltraRAG) — RAG 框架
- [Anthropic Skills](https://github.com/anthropics/skills) — Agent 技能框架和内置技能（skill-creator）
- [Vercel Labs Skills](https://github.com/vercel-labs/skills) — find-skills 技能
- [MiniMax-AI Skills](https://github.com/MiniMax-AI/skills) — minimax-pdf 技能
- [frontend-slides](https://github.com/zarazhangrui/frontend-slides) — 用编程 Agent 的前端能力创建精美网页幻灯片
- [Karpathy Guidelines](https://x.com/karpathy/status/2015883857489522876) — LLM 编码行为准则
- [Vite](https://github.com/vitejs/vite) — 前端构建工具
- [React](https://github.com/facebook/react) — UI 框架
- [Tailwind CSS](https://github.com/tailwindlabs/tailwindcss) — 原子化 CSS 框架
- [shadcn/ui](https://github.com/shadcn-ui/ui) — 可访问的 React 组件原语

***

## ⭐ 支持我们

如果您觉得 HcEngine 对您的工作或研究有帮助，请点亮一颗 Star 支持我们！

***

## 📝 引用

```bibtex
@misc{HcEngine2026,
  author       = {HcEngine Team},
  title        = {HcEngine: A WorkSpace-Centric Open-Source Agent Operating System},
  howpublished = {\url{https://gitee.com/jackgoogle/hc-engine}},
  year         = {2026},
  note         = {Accessed: 2026-06-26}
}
```

## 📄 许可证

本项目基于 [GNU Affero General Public License v3.0](LICENSE) 开源。