# ByClaw
**Repository Path**: smartchart/ByClaw
## Basic Information
- **Project Name**: ByClaw
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-22
- **Last Updated**: 2026-07-22
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# 
ByClaw — 企业级智能体执行框架
鲸智百应 · 重塑人机协作，驱动组织进化
中文 | English
90% 的企业在智能体转型中卡在"最后一公里"——概念很火、试点很美，但一规模化、一进生产、一碰核心数据，就遇到四大死结：**不敢用、不会用、接不通、算不清**。
我们总结了智能体组织的必赢公式：
> **可持续竞争力 = AI 原生思维 × 智能体组织架构 × 人机共生文化 × 可信技术底座**
四者缺一不可。没有安全可控、可规模化、可沉淀的技术底座，所有智能体转型都只能停留在演示阶段。
**ByClaw（鲸智百应）** 就是为解决这个问题而生——企业级智能体组织操作系统，支撑新质生产力的可信 AI 底座。它是 OpenClaw 的"企业增强版"，在开源智能体内核之上叠加了企业生产环境所需的核心能力：多租户隔离、统一安全网关、合规沙箱、长程任务支持、动态算力分配与释放。从一个 Agent 的 PoC 到千人组织的全面落地，ByClaw 提供完整的技术底座——**让企业敢部署、CEO 敢拍板、CIO 敢签字、CFO 敢算账**。
[核心亮点](#核心亮点) · [架构总览](#架构总览) · [快速开始](#快速开始) · [痛点与方案](#痛点与解决方案) · [参与贡献](CONTRIBUTING.md) · [安全策略](SECURITY.md)
---
## 核心亮点
- **数字员工** — 可视化创建、部署和管理超级助手、个人助理、数字员工，它们拥有明确的岗位职责
- **多智能体协作** — 通过异步事件、控制流与数据流分离两种核心技术：实现多智能体之间的协作，控制流与数据流分离，解决多智能体参与的长程任务碰到的问题
- **智能反向代理** — 将多个 MCP/Skill 能力压缩到恒定级别的上下文，多智能体生产级运行的"中枢神经系统"
- **多租户运行时** — 单实例统一部署、统一管理，支撑整个组织
- **统一安全网关** — 身份认证、会话管控、零信任访问
---
## 架构总览
ByClaw 采用“统一接入、集中治理、分布执行、资源隔离”的整体架构。平台把 Web、钉钉等入口统一收敛到安全网关和后端服务，由后端完成认证、会话、资源、权限、路由与编排，再把智能体任务分发给 DataCloud、QA、OpenClaw、OpenSandbox 等执行与能力服务。业务数据、知识文件、会话状态、执行结果分别落在数据库、Redis、MinIO 与个人沙箱中，形成可审计、可扩展、可隔离的企业级智能体运行底座。
```
用户 / 业务系统 / 钉钉 / Web
│
▼
Nginx / 统一接入层
│
▼
byclaw-fe ── REST / WebSocket / SSE ── byclaw-be
│
┌───────────────────────────┼───────────────────────────┐
▼ ▼ ▼
byclaw-qa byclaw-data byclaw-exe
知识库 / QA Worker DataCloud / MCP Worker Skills / Extensions
│ │ │
└───────────────┬───────────┴───────────┬───────────────┘
▼ ▼
OpenClaw / OpenSandbox 业务 API / 外部系统
│
▼
OpenGauss / Redis / MinIO / 文件挂载 / 个人沙箱空间
```
### 业务架构
ByClaw 面向“组织中的智能体生产力”建模，核心业务对象包括用户、组织、岗位、数字员工、知识、工具、对象、视图、会话与任务。
```mermaid
flowchart LR
org["组织 / 岗位 / 成员"] --> perm["角色 / 权限组 / 访问令牌"]
org --> employee["数字员工"]
employee --> profile["岗位职责 / 提示词 / 模型策略"]
employee --> resources["资源编排"]
resources --> knowledge["业务知识"]
resources --> tools["业务工具"]
resources --> objects["业务对象"]
resources --> views["业务视图"]
user["用户"] --> session["对话会话"]
session --> task["长程任务 / 异步任务"]
task --> employee
task --> result["执行结果 / 任务状态 / 审计记录"]
admin["管理后台"] --> org
admin --> employee
admin --> resources
```
- **组织与权限**：支持组织、岗位、成员、权限组、访问令牌等管理能力，为企业内部多角色协同提供统一身份与权限基础。
- **数字员工**：将智能体抽象为可配置、可发布、可运行的数字员工，包含岗位职责、模型配置、知识资源、工具资源和运行策略。
- **对话与任务**：以聊天会话作为人机协作入口，支持流式回复、上下文记忆、长程任务、异步执行和执行结果回传。
- **资源中心**：统一管理业务工具、业务对象、业务视图、业务知识和技能，让智能体按需加载上下文和能力。
- **管理后台**：提供模型、沙箱、组织、资源、数字员工等运营管理能力，支撑从 PoC 到生产运行的完整生命周期。
### 应用架构
应用层按职责拆分为前端、后端、数据云、QA、扩展执行和中间件服务。
```mermaid
flowchart TB
client["Web / 钉钉 / 移动端 / 业务系统"] --> nginx["Nginx 接入层"]
nginx --> fe["byclaw-fe
门户 / 控制台 / 对话界面"]
fe --> be["byclaw-be
核心 API / 认证授权 / 资源治理 / 网关路由"]
be --> ws["WebSocket / SSE
流式会话"]
be --> qa["byclaw-qa
知识库管理 / QA Worker"]
be --> data["byclaw-data
DataCloud MCP / Gateway Worker"]
be --> exe["byclaw-exe
Skills / Extensions"]
be --> sandbox["OpenSandbox
隔离执行环境"]
sandbox --> sandboxRuntime["沙箱容器
byclaw-openclaw / Agent Runtime"]
data --> sandboxRuntime
exe --> sandboxRuntime
qa --> infra["Redis / OpenGauss / MinIO"]
data --> infra
be --> infra
```
| 模块 | 职责 | 关键能力 |
|------|------|----------|
| `byclaw-fe` | Web 门户与管理控制台 | 对话、知识中心、数字员工、工作中心、工具中心、沙箱页面、移动端适配 |
| `byclaw-be` | 核心业务后端与统一网关 | 认证授权、会话管理、资源管理、数字员工管理、文件管理、Feign 调用、WebSocket |
| `byclaw-qa` | 知识库与问答服务 | 知识导入、索引构建、检索问答、QA Worker、知识资源映射 |
| `byclaw-data` | 数据云与智能体执行服务 | DataCloud MCP、Gateway Worker、数据查询分析、工具调用、结果文件存储 |
| `byclaw-exe` | 扩展插件与技能脚本 | Skills、Extensions、业务脚本、能力扩展 |
| `middleware` | 基础运行组件 | Redis、MinIO、OpenGauss、OpenSandbox 等运行依赖 |
同步链路以 REST、WebSocket、SSE 和 Feign 为主，异步链路以 Redis Pub/Sub、Redis Stream、Worker 消费和后台任务为主。控制流由后端统一编排，数据流按资源类型进入数据库、对象存储、缓存、沙箱或外部业务系统。
### 数据架构
ByClaw 将数据分为业务元数据、会话状态、知识文件、执行结果和运行配置五类，避免所有数据被塞进单一存储。
- **OpenGauss / PostgreSQL**：存储用户、组织、权限、数字员工、资源元数据、知识库索引任务、系统配置等结构化数据。
- **Redis**：承载登录会话、缓存、分布式锁、数字员工配置快照、Pub/Sub 通知和 Worker 消息通道。
- **MinIO / OSS / SFTP**：保存上传文件、知识库原始文件、Markdown 转换结果、附件和大结果文件。
- **向量与检索数据**：由 QA / DataCloud 服务负责知识切分、索引构建、检索投影和召回，服务于 RAG 与问答场景。
- **个人数据空间**：为员工或智能体提供独立文件空间和沙箱挂载路径，实现“数随人走、多智能体共享、敏感数据少落盘”。
数据访问遵循“元数据进库、文件进对象存储、热状态进缓存、执行隔离进沙箱”的原则，便于扩展、审计和故障恢复。
### 技术架构
ByClaw 采用多语言、多运行时的组合架构：Java 负责核心业务和企业级治理，TypeScript 负责前端体验，Python 负责智能体、知识和数据执行。
```mermaid
flowchart TB
ui["前端体验层
React / Umi Max / TypeScript / Ant Design"] --> api["企业治理层
Java 21 / Spring Boot / Spring Security / MyBatis"]
api --> agent["智能体能力层
Spring AI / LangChain4j / MCP / OpenClaw / by-framework"]
agent --> py["Python 执行层
by-qa / by-datacloud / Skills / Workers"]
api --> comm["通信层
REST / WebSocket / SSE / Feign / Redis PubSub"]
py --> comm
comm --> storage["存储与状态层
OpenGauss / Redis / MinIO / 文件挂载"]
py --> runtime["隔离运行层
OpenClaw / OpenSandbox / 容器运行时"]
runtime --> storage
devops["工程化
Docker Compose / pnpm / Maven / uv / GitHub Actions"] -.-> ui
devops -.-> api
devops -.-> py
```
| 层次 | 技术选型 | 说明 |
|------|----------|------|
| 前端 | React 18、Umi Max 4、TypeScript、Ant Design 5 | 企业级 Web 控制台与对话体验 |
| 后端 | Java 21、Spring Boot 3.4、Spring Security、Spring Session、MyBatis | 核心 API、认证授权、资源治理、服务编排 |
| AI / Agent | Spring AI、LangChain4j、MCP、OpenClaw、by-framework、by-qa、by-datacloud | 模型接入、智能体执行、知识问答、数据分析 |
| 通信 | REST、WebSocket、SSE、OpenFeign、Redis Pub/Sub | 同步请求、流式响应、服务间调用和异步通知 |
| 存储 | OpenGauss / PostgreSQL、Redis、MinIO、文件挂载 | 结构化数据、缓存消息、对象文件和沙箱数据 |
| 工程化 | Docker Compose、pnpm、Maven、uv、GitHub Actions | 本地开发、镜像构建、依赖管理和 CI/CD |
### 部署架构
ByClaw 支持本地开发、单机 Compose 和拆分部署。默认部署形态由 `deploy/middleware` 和 `deploy/standalone` 两组 Compose 文件组成。
```mermaid
flowchart TB
user["用户 / 企业入口"] --> lb["域名 / 负载均衡 / HTTPS"]
lb --> feC["byclaw-fe
Nginx + 静态资源"]
feC --> beC["byclaw-be
HTTP 8086 / WS 8082"]
beC --> qaApi["byclaw-qa-manager
API 8000"]
beC --> qaWorker["byclaw-qa-worker
后台消费"]
beC --> dataC["byclaw-data
DataCloud 8087 / Worker"]
beC --> sandboxC["OpenSandbox
沙箱调度 / 租约管理"]
sandboxC --> sandboxContainer["沙箱容器
按需拉起 / 自动回收"]
sandboxContainer --> openclawC["byclaw-openclaw
Agent Runtime"]
subgraph middleware["deploy/middleware"]
redisC["Redis"]
dbC["OpenGauss"]
minioC["MinIO"]
end
beC --> redisC
beC --> dbC
beC --> minioC
qaApi --> redisC
qaApi --> dbC
qaApi --> minioC
qaWorker --> redisC
dataC --> redisC
dataC --> minioC
sandboxContainer --> mount["文件挂载 / 个人数据空间"]
minioC --> mount
```
- **中间件层**：先启动 Redis、MinIO、OpenGauss、OpenSandbox 等基础组件；OpenSandbox 负责按需拉起沙箱容器。
- **应用层**：启动 `byclaw-fe`、`byclaw-be`、`byclaw-qa-manager`、`byclaw-qa-worker`、`byclaw-data`。
- **接入层**：前端容器内置 Nginx，统一暴露 HTTP / HTTPS 入口，并转发后端 API、WebSocket、文件浏览和沙箱相关请求。
- **配置层**：通过根目录 `.env` 和 `deploy/config` 注入数据库、Redis、MinIO、模型、沙箱、端口和域名配置。
- **执行层**：`byclaw-openclaw` 运行在 OpenSandbox 拉起的沙箱容器中，Skills、Extensions 和外部业务 API 通过沙箱执行环境按需加载。
在生产环境中，可以将数据库、缓存、对象存储、QA Worker、DataCloud Worker 和 OpenSandbox 分别扩容；前端与后端保持无状态或弱状态部署，通过 Redis 和数据库共享状态。
### 安全架构
ByClaw 的安全设计围绕“身份可信、资源可控、执行隔离、链路可审计”展开。
```mermaid
flowchart LR
user["用户 / 渠道身份"] --> auth["认证
登录会话 / JWT / Access Token"]
auth --> gateway["统一安全网关
签名校验 / 会话校验 / 路由控制"]
gateway --> authz["授权
组织 / 岗位 / 角色 / 权限组 / 资源授权"]
authz --> resource["资源访问
知识 / 工具 / 对象 / 视图 / 文件"]
authz --> agentAuth["数字员工授权
可见 / 可用 / 可执行"]
agentAuth --> agent["数字员工执行"]
agent --> sandbox["个人运行环境
独立沙箱 / 租约 / 自动释放"]
sandbox --> dataSpace["个人数据隔离
按用户挂载 / 数随人走"]
sandbox --> async["异步消息驱动
Redis Stream / PubSub / Worker"]
async --> noPort["沙箱进程零端口暴露
不直接对外开放服务端口"]
resource --> dataGuard["数据保护
对象存储 / 按需加载 / 敏感数据少落盘"]
dataSpace --> dataGuard
gateway --> audit["审计追踪
日志 / 会话 / 任务状态 / 资源变更"]
agentAuth --> audit
async --> audit
dataGuard --> audit
```
- **身份认证**：支持登录会话、JWT、访问令牌和第三方渠道身份接入，统一收敛到后端认证体系。
- **权限控制**：通过组织、岗位、角色、权限组和资源授权控制用户可见、可用、可管理的业务资源。
- **网关治理**：后端作为统一安全网关，负责请求签名校验、会话校验、路由控制、文件访问控制和渠道接入。
- **数字员工授权**：数字员工在可见、可用、可执行三个层面接受授权控制，用户只能调用被授权的数字员工及其绑定资源。
- **个人环境隔离**：每个用户拥有独立沙箱运行环境，沙箱按需申请、租约管理、用完释放或自动过期，避免不同用户的执行空间相互影响。
- **个人数据隔离**：个人数据空间按用户隔离和挂载，数字员工执行时访问的是当前用户授权范围内的数据，实现“数随人走”。
- **零端口暴露**：沙箱容器内进程不直接向外暴露业务端口，任务通过 Redis Stream、Pub/Sub、Worker 等异步消息机制驱动和回传。
- **数据保护**：敏感配置通过环境变量注入，文件进入对象存储，工具调用按需加载业务资源，减少敏感数据在模型上下文和本地磁盘中的长期驻留。
- **审计与追踪**：日志、任务状态、会话记录、资源变更和执行结果可沉淀为审计线索，支撑问题回溯和合规检查。
---
## 快速开始
### 环境要求
| 工具 | 版本要求 | 验证命令 |
|------|---------|---------|
| Docker & Compose V2 | 最新版 | `docker compose version` |
| Node.js | >= 18.20 | `node --version` |
| pnpm | >= 9.x | `pnpm --version` |
| JDK | 21 | `java -version` |
| Maven | >= 3.8 | `mvn --version` |
| Python | >= 3.12 | `python3 --version` |
| uv | 任意版本 | `uv --version` |
### Docker 一键部署
```bash
# 1. 克隆仓库
git clone https://github.com/beyonai/ByClaw.git
cd ByClaw
# 2. 配置环境变量
cp .env.example .env
# ⚠️ 重要：.env.example 中所有地址默认为 127.0.0.1，
# 你需要根据 deploy/middleware 中各中间件实际暴露的端口，
# 逐项回填 DB_URL、DB_USER、DB_PASS、REDIS_HOST、REDIS_PORT、
# REDIS_PASSWORD、MID_FTP_* 等配置。
# 如果中间件部署在远程机器，请替换为对应 IP。
# 3. 在 .env 中选择存储方案
# BYCLAW_DEPLOY_STORAGE=nfs # 推荐：OpenClaw /by 和 BE 文件 CRUD 都走 /mnt/byclaw-file
# BYCLAW_DEPLOY_STORAGE=minio # 兼容旧 MinIO/rclone 方案
# BYCLAW_DEPLOY_STORAGE=nfs-hybrid # OpenClaw /by 走 NFS，上传下载 API 继续走 MinIO
# 4. 首次部署：按 .env 拉镜像、可选初始化 NFS、启动中间件和应用
sh deploy.sh init
# 5. 增量更新：按 .env 重新生成配置并重建服务，不重复初始化 NFS
# sh deploy.sh update
```
访问 **http://localhost:8080** 开始使用。
### 本地开发
本地开发同样需要先配置 `.env` 文件（步骤与上方 Docker 部署一致）。
中间件可以部署在本地，也可以部署在远程服务器——只需在 `.env` 中将 `127.0.0.1` 替换为远程服务器的 IP 和端口即可。
```bash
# 1. 配置环境变量（同上，必须先完成）
cp .env.example .env
# 根据中间件实际地址回填 DB_URL、REDIS_HOST 等
# 2. 拉取并启动中间件（本地部署时执行，远程部署则跳过此步）
(cd deploy/middleware && sh pull.sh && sh start-all.sh)
# 3. 启动应用（推荐统一脚本）
scripts/start.sh --all
# 按模块启动
scripts/start.sh --fe # 前端 :8000
scripts/start.sh --be # 后端 :8086
scripts/start.sh --qa # QA 服务
scripts/start.sh --data # 数据云服务
# 停止服务
scripts/stop.sh # 停止全部
scripts/stop.sh --fe # 仅停止前端
```
启动脚本会自动执行**环境预检**——校验所有工具、版本和依赖是否就绪，有问题会立即报错并给出修复建议。使用 `--skip-checks` 可跳过预检。
前端开发服务器运行在 http://localhost:8000，自动代理 API 请求到后端。
---
## 项目结构
```
ByClaw/
├── byclaw-fe/ # Web 前端（React, Umi Max, TypeScript）
├── byclaw-be/ # 后端服务（Spring Boot 3.4, Java 21）
├── byclaw-data/ # 数据云服务（Python 3.12, uv）
├── byclaw-qa/ # QA 与 Agent 服务（Python 3.12, uv）
├── byclaw-exe/ # 扩展插件与技能脚本
├── deploy/ # Docker Compose 部署配置
├── docs/ # 项目文档
├── scripts/ # 开发自动化脚本（start/stop/deploy）
└── .github/ # CI/CD 工作流与模板
```
---
## 端口说明
| 服务 | 默认端口 |
|------|:--------:|
| 前端（Nginx） | 8080 |
| 后端 HTTP | 8086 |
| 后端 WebSocket | 8082 |
| QA Manager | 8000 |
| DataCloud | 8087 |
| Redis | 6379 |
| MinIO API / Console | 9000 / 9001 |
| OpenGauss | 5432 |
| OpenSandbox | 9005 |
---
## 提交规范
使用 [Conventional Commits](https://www.conventionalcommits.org/)，scope 为模块名：
```
feat(fe): 新增对话历史搜索
fix(be): 修复分页边界问题
docs: 更新部署文档
```
详见 [.github/commit-convention.md](.github/commit-convention.md)。
---
## 参与贡献
欢迎参与！请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解贡献流程。
使用 [Pull Request 模板](.github/PULL_REQUEST_TEMPLATE.md) 提交 PR。
---
## 社区
- [GitHub Issues](https://github.com/beyonai/ByClaw/issues) — Bug 反馈与功能建议
- [GitHub Discussions](https://github.com/beyonai/ByClaw/discussions) — 问题讨论与想法交流
- [安全策略](SECURITY.md) — 漏洞负责任披露
---
## 许可证
[Apache License 2.0](LICENSE)
---
由 BeyondAI 构建 · 站在未来，看见今天。