启动 OpenSandbox Server（需先配置 .sandbox.toml）

June 13, 2026 · View on GitHub

DeepClaw

快速开始 · 核心能力 · 界面预览 · API 接口 · 配置说明 · 项目结构

DeepClaw 是一个开源的 Agent / RAG 脚手架，把通用 Agent、RAG 知识库、技能管理、渠道接入、MCP 配置和静态前端整合到同一个 FastAPI 服务中，适合快速搭建企业知识问答、自动化助手、内部 Copilot 和多工具智能体应用。

核心能力

能力	说明
通用 Agent	基于 LangGraph / DeepAgents 构建，支持工具调用、SSE 流式输出、MCP 配置透传
RAG 知识库	支持知识库创建、文档上传、切片查看、图检索 RAG 和独立 RAG 问答
多模态输入	通用接口 `query` 支持纯文本与图文混合结构
技能管理	支持技能列表、上传和删除
渠道接入	内置飞书、钉钉、微信 ClawBot 路由和会话管理
多执行后端	支持 `local_shell`、`store`、`sandbox` 三种执行模式
多用户沙箱隔离	`sandbox` 模式下每个用户拥有独立的 OpenSandbox 容器，工作区、技能目录和会话历史完全隔离
前端界面	Next.js + React 聊天 UI，构建后由 FastAPI 的 `/` 统一托管
可观测性	可选接入 Phoenix tracing、Postgres 长期记忆和 Tavily 搜索

界面预览

以下界面覆盖项目当前的主要工作流，包括聊天、人工确认、知识库、技能管理、MCP 管理、渠道管理和用户隔离。

聊天主界面

聊天界面

统一承载 Agent 对话、工具调用流式输出和核心交互入口。

Human in the Loop 人工确认

Human in the Loop

展示工具调用进入人工确认后的审批与参数编辑流程。

知识库管理

用于查看知识库列表、知识详情、文档分页和切片明细。

技能管理

用于上传、删除和维护工作区技能目录。

MCP 管理

用于维护 MCP 配置，并控制通用 Agent 请求是否附带 MCP 服务定义。

渠道管理

用于管理飞书、钉钉、微信 ClawBot 渠道接入、用户绑定和会话回复模式。

用户管理

用于切换和维护不同用户身份，隔离对话、知识库和渠道数据。

技术栈

模块	技术
后端	FastAPI, LangGraph, DeepAgents, LangChain
RAG	Elasticsearch, Dense Vector, BM25, Graph RAG
前端	Next.js 15, React 19, TypeScript
执行后端	Local Shell, Store Backend, OpenSandbox（Docker 容器沙箱）
多用户隔离	基于 OpenSandbox 的每用户独立容器 + 绑定卷隔离
可选组件	Phoenix, Tavily, PostgresStore, OpenSandbox Server
包管理	uv, pnpm

项目结构

deepclaw/
├── deepclaw/
│   ├── agents/              # 通用 Agent / RAG Agent 组装、上下文与状态
│   ├── backend/             # 执行后端（含 OpenSandbox 沙箱隔离实现）
│   ├── common/              # Elasticsearch、Graph RAG、文本切分等通用实现
│   ├── middleware/          # 业务开关、RAG 注入、MCP、工具搜索、沙箱清理等中间件
│   ├── patch/               # 第三方库补丁与适配
│   ├── tools/               # 天气、网页抓取、检索、定时任务等工具
│   ├── web_backend/         # FastAPI Web 应用层与所有 Web 功能目录
│   ├── main.py              # 主启动入口
│   └── settings.py          # 环境变量配置
├── frontend/                # Next.js 前端
├── .deepclaw/               # 运行时工作区、技能目录、渠道数据库等
├── .sandbox.toml            # OpenSandbox Server 配置（sandbox 模式必需）
├── user_workspace/          # 用户工作区目录（sandbox 模式每用户独立子目录）
├── assets/                  # 截图和 Elasticsearch 插件
└── docker-compose.yml       # PostgreSQL / Elasticsearch / Phoenix

系统架构

┌──────────────────────────────────────────────────────────────────────┐
│                         接入层 Access                                 │
│  ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐     │
│  │  Next.js 前端     │ │  飞书适配        │ │  钉钉适配        │     │
│  │  (frontend/out)  │ │ (长连接+WebSocket)│ │ (Webhook)       │     │
│  └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘     │
│  ┌──────────────────┐ ┌──────────────────┐          │               │
│  │  微信 ClawBot     │ │  其他渠道...     │          │               │
│  │ (二维码+轮询)     │ │                  │          │               │
│  └────────┬─────────┘ └────────┬─────────┘          │               │
│           │                    │                    │               │
│           └────────────┬───────┴────────────────────┘               │
│                        ▼                                            │
└──────────────────────────────────────────────────────────────────────┘
              ┌────────────────────────────────────┐
              │        POST /api/agent/general_api  │
              │        POST /api/rag/general_api    │
              │        POST /api/auth/*             │
              │        POST /api/channels/sessions  │
              └────────────────┬───────────────────┘
                               │
┌──────────────────────────────────────────────────────────────────────┐
│                       API 层 / FastAPI                                │
│  ┌──────────┐ ┌──────────────┐ ┌──────────────┐ ┌────────────────┐  │
│  │  认证路由  │ │  Agent 路由   │ │  RAG 路由     │ │  渠道管理路由   │  │
│  │ /api/auth │ │ /api/agent   │ │ /api/rag     │ │ /api/channels │  │
│  └────┬─────┘ └──────┬───────┘ └──────┬───────┘ └───────┬────────┘  │
│       │              │               │                 │            │
└───────┼──────────────┼───────────────┼─────────────────┼────────────┘
        ▼              ▼               ▼                 ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│   认证服务         │ │   通用 Agent     │ │   RAG Agent      │ │   渠道服务        │
│   SQLModel        │ │ LangGraph+Agent  │ │   LangChain      │ │ Binding · Session│
└──────────────────┘ │  中间件流水线     │ │   RAGMiddleware  │ │ Dispatcher       │
                     │  Prompt→业务→    │ └────────┬─────────┘ └──────────────────┘
                     │  MCP→RAG→规划→   │          │
                     │  Cron→沙箱       │          │
                     └────────┬─────────┘          │
                              │                    │
                              ▼                    ▼
┌──────────────────────────────────────────────────────────────────────┐
│                      基础设施 Infrastructure                         │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ES 向量检索│ │PostgreSQL│ │  SQLite  │ │  Docker  │ │LLM API   │  │
│  │+关键词检索│ │长期记忆   │ │渠道数据   │ │沙箱容器   │ │OpenAI兼容│  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
│  ┌───────────────────────────────────────────────────────────────┐  │
│  │  Phoenix 分布式追踪                                           │  │
│  └───────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘

快速开始

1. 环境要求

场景	依赖
仅运行后端和已构建前端	Python `>= 3.12`、`uv`、Docker / Docker Compose
开发或重新构建前端	额外需要 Node.js `>= 18`、`pnpm`

如果仓库里的 frontend/out 已经存在，且你不修改前端代码，可以直接跳过前端安装和构建步骤。

2. 初始化后端

cp .env.example .env
uv sync --dev

如果要启用 OpenSandbox：

uv sync --dev --extra opensandbox

3. 配置 `.env`

至少填入：

OPENAI_API_KEY=your-api-key
OPENAI_API_BASE=http://localhost:8082/v1
CHAT_MODEL_NAME=qwen3
EMBEDDING_MODEL_NAME=qwen3-embedding
ES_URL=http://localhost:9200
ES_URSR=elastic
ES_PWD=elastic@2024

4. 启动主服务

统一从 main 入口启动：

uv run python -m deepclaw.main

服务启动后：

前端页面：http://localhost:7869/
Agent SSE：POST /api/agent/general_api
Agent AG-UI：POST /api/agent/ag_ui
RAG SSE：POST /api/rag/general_api
Channels API：/api/channels/*

5. 启动依赖服务（可选，但推荐）

如果用到 Elasticsearch 知识库或 Postgres 长期记忆，需启动对应服务：

docker-compose up -d postgresql elasticsearch

如需 Phoenix 观测：

docker-compose up -d phoenix

Phoenix 控制台默认地址：http://localhost:6006

6. 启动 OpenSandbox 服务（可选，仅 sandbox 模式需要）

如果使用 BACKEND_TYPE=sandbox，需要额外启动 OpenSandbox Server 并拉取镜像：

# 拉取所需镜像
docker pull sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2
docker pull opensandbox/execd:v1.0.16
docker pull opensandbox/egress:v1.0.12

# 启动 OpenSandbox Server（需先配置 .sandbox.toml）
opensandbox-server --config .sandbox.toml

7. 前端开发

仅在你需要开发或重新构建前端时执行：

cd frontend
pnpm install
pnpm dev

开发模式地址：http://localhost:3000

构建静态前端并交给后端托管：

cd frontend
pnpm build

API 接口

Agent

方法	路径	协议	用途
`POST`	`/api/agent/ag_ui`	AG-UI	Agent 前端协议接口
`POST`	`/api/agent/general_api`	SSE	通用 Agent 流式接口
`POST`	`/api/agent/skills/list`	REST	技能列表
`POST`	`/api/agent/skills/upload`	REST	上传技能 zip
`POST`	`/api/agent/skills/delete`	REST	删除技能

RAG

方法	路径	协议	用途
`POST`	`/api/rag/general_api`	SSE	RAG 流式问答
`POST`	`/api/rag/knowledge-bases/list`	REST	知识库分页列表
`POST`	`/api/rag/knowledge-bases/create`	REST	创建知识库
`POST`	`/api/rag/knowledge-bases/detail`	REST	知识库详情
`POST`	`/api/rag/knowledge-bases/update`	REST	更新知识库
`POST`	`/api/rag/knowledge-bases/delete`	REST	删除知识库
`POST`	`/api/rag/knowledge-bases/bulk-delete`	REST	批量删除知识库
`POST`	`/api/rag/knowledge-bases/documents/list`	REST	文档分页列表
`POST`	`/api/rag/knowledge-bases/documents/detail`	REST	文档切片详情
`POST`	`/api/rag/knowledge-bases/documents/upload`	REST	上传文档
`POST`	`/api/rag/knowledge-bases/documents/update`	REST	更新文档展示名
`POST`	`/api/rag/knowledge-bases/documents/delete`	REST	删除文档
`POST`	`/api/rag/knowledge-bases/documents/bulk-delete`	REST	批量删除文档

Channels

方法	路径	协议	用途
`POST`	`/api/channels/feishu/events`	REST	飞书事件入口
`POST`	`/api/channels/dingtalk/events`	REST	钉钉事件入口
`POST`	`/api/channels/weixin-clawbot/qrcode`	REST	获取微信 ClawBot 登录二维码
`GET`	`/api/channels/weixin-clawbot/qrcode/status`	REST	查询二维码状态
`POST`	`/api/channels/weixin-clawbot/users/{user_id}/qrcode`	REST	生成用户绑定二维码
`GET`	`/api/channels/weixin-clawbot/users`	REST	列出已绑定用户
`DELETE`	`/api/channels/weixin-clawbot/users/{user_id}`	REST	删除绑定
`GET`	`/api/channels/sessions`	REST	列出渠道会话
`PATCH`	`/api/channels/sessions/{session_id}`	REST	更新会话回复模式

使用示例

通用 Agent 问答

curl -N -X POST http://localhost:7869/api/agent/general_api \
  -H "Content-Type: application/json" \
  -d '{
    "query": "帮我总结一下今天的工作安排",
    "session_id": "demo-session",
    "user_id": "demo-user",
    "internet_search": false,
    "deep_thinking": false
  }'

多模态 Agent 输入

curl -N -X POST http://localhost:7869/api/agent/general_api \
  -H "Content-Type: application/json" \
  -d '{
    "query": [
      { "type": "text", "text": "这张图片里有什么？" },
      {
        "type": "image",
        "url": "https://example.com/demo.jpg",
        "mime_type": "image/jpeg"
      }
    ],
    "session_id": "multi-modal-session",
    "user_id": "demo-user"
  }'

创建知识库

curl -X POST http://localhost:7869/api/rag/knowledge-bases/create \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "demo-user",
    "name": "产品文档",
    "description": "示例知识库"
  }'

上传文档

curl -X POST http://localhost:7869/api/rag/knowledge-bases/documents/upload \
  -F "user_id=demo-user" \
  -F "knowledge_base_id=<knowledge_base_id>" \
  -F "files=@./demo.pdf"

调用 RAG 流式问答

index_name 和 graph_name 可从知识库详情返回值中的 passage_index、index_prefix 获取。

curl -N -X POST http://localhost:7869/api/rag/general_api \
  -H "Content-Type: application/json" \
  -d '{
    "query": "这份文档的核心结论是什么？",
    "session_id": "rag-session",
    "user_id": "demo-user",
    "index_name": "kb_xxx_passages",
    "graph_name": "kb_xxx"
  }'

配置说明

必填环境变量

变量	说明
`OPENAI_API_BASE`	OpenAI-compatible LLM API 地址
`OPENAI_API_KEY`	LLM API 密钥
`CHAT_MODEL_NAME`	聊天模型名称
`EMBEDDING_MODEL_NAME`	向量模型名称
`ES_URL`	Elasticsearch 地址
`ES_URSR`	Elasticsearch 用户名
`ES_PWD`	Elasticsearch 密码

常用可选环境变量

变量	说明
`BACKEND_TYPE`	执行后端：`local_shell`（默认）/ `store` / `sandbox`
`OPEN_SANDBOX_CODE_INTERPRETER_IMAGE`	Sandbox 代码解释器镜像地址（默认：`sandbox-registry.cn-zhangjiakou.cr.aliyuncs.com/opensandbox/code-interpreter:v1.0.2`）
`PG_DATABASE_URL`	启用 PostgresStore 长期记忆
`TAVILY_API_KEY`	启用联网搜索工具
`USE_TOOL_SEARCH`	启用延迟工具搜索
`USE_COPILOTKIT`	启用 CopilotKit 中间件
`PHOENIX_COLLECTOR_ENDPOINT`	启用 Phoenix tracing
`AUTH_ADMIN_EMAIL`	默认管理员邮箱
`AUTH_ADMIN_PASSWORD`	默认管理员密码
`AUTH_TOKEN_EXPIRE_DAYS`	登录态有效期天数
`CHANNEL_AGENT_API_URL`	渠道网关调用 Agent 的地址
`WEIXIN_CLAWBOT_*`	微信 ClawBot 相关配置

沙箱模式（多用户工作隔离）

当 BACKEND_TYPE=sandbox 时，系统使用 OpenSandbox 为每个用户创建独立的 Docker 容器作为执行环境，实现多用户工作隔离。

隔离机制

隔离维度	说明
容器隔离	每个用户拥有独立的 OpenSandbox 容器，进程和文件系统完全隔离
工作区隔离	每个用户的工作区映射到 `user_workspace/{user_id}/.deepclaw/`，通过 Docker bind mount 挂载
技能目录隔离	私有技能目录（`/.deepclaw/workspace/skills`）随用户独立挂载，同时共享公共技能目录（`/workspace/skills`）
会话历史隔离	对话历史写入各自独立的 `conversation_history` 目录
生命周期管理	每次 Agent 执行完毕后，`OpenSandboxKillMiddleware` 自动杀死当前用户沙箱并清理状态

执行流程

Agent 启动时检查 BACKEND_TYPE，若为 sandbox 则加载 OpenSandbox 后端
首次执行时，get_sandbox() 为当前 user_id 创建新沙箱，在 runtime store 中持久化 sandbox_id
后续执行复用已有沙箱（通过 sandbox_id 重连）
沙箱内支持：命令执行（execute）、文件读写（write/read）、文件编辑（edit）、文件上传下载（upload_files/download_files）
Agent 执行完毕后，OpenSandboxKillMiddleware.after_agent 自动杀死沙箱并删除 store 中的记录

前提条件

Docker 环境
OpenSandbox Server 已启动（参考上文步骤 5）
正确配置 .sandbox.toml（项目根目录已有示例配置）
安装 opensandbox 额外依赖：uv sync --dev --extra opensandbox

配置文件 `.sandbox.toml`

项目根目录的 .sandbox.toml 是 OpenSandbox Server 的配置文件，关键项：

[server]
host = "127.0.0.1"
port = 8089

[runtime]
type = "docker"
execd_image = "docker.1ms.run/opensandbox/execd:v1.0.16"

[storage]
allowed_host_paths = ["/home/dev/liuyu/project/langchain-api"]

allowed_host_paths 必须包含项目根目录，否则 bind mount 会被拒绝。

常见说明

后端会直接挂载 frontend/out。如果该目录已经存在，纯运行场景不需要安装 Node.js 和 pnpm。
前端修改后，必须重新执行 pnpm build，后端 / 才会提供最新页面。
默认工作区位于 .deepclaw/workspace。
渠道模块默认把 SQLite 数据库写入 .deepclaw/channels.db。
如果 frontend/out 不存在，后端仍可提供 API，但 / 不会挂载前端页面。
沙箱模式（BACKEND_TYPE=sandbox）需要先启动 OpenSandbox Server 并正确配置 .sandbox.toml，详见上方的「沙箱模式」章节。

License

Apache-2.0