{"id":50696871,"url":"https://github.com/shell-nlp/deepclaw","last_synced_at":"2026-06-09T07:02:28.735Z","repository":{"id":332536347,"uuid":"1124147115","full_name":"shell-nlp/deepclaw","owner":"shell-nlp","description":"deepclaw，一个开源的 agent/rag 脚手架","archived":false,"fork":false,"pushed_at":"2026-06-07T16:58:48.000Z","size":22544,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-07T18:22:27.937Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shell-nlp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-28T12:44:23.000Z","updated_at":"2026-06-07T16:58:38.000Z","dependencies_parsed_at":null,"dependency_job_id":"173e8ea8-228d-4192-9600-b4c1df63eac4","html_url":"https://github.com/shell-nlp/deepclaw","commit_stats":null,"previous_names":["shell-nlp/langchain-api","shell-nlp/deepclaw"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/shell-nlp/deepclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shell-nlp%2Fdeepclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shell-nlp%2Fdeepclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shell-nlp%2Fdeepclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shell-nlp%2Fdeepclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shell-nlp","download_url":"https://codeload.github.com/shell-nlp/deepclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shell-nlp%2Fdeepclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34095247,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-09T02:00:06.510Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-09T07:02:27.965Z","updated_at":"2026-06-09T07:02:28.728Z","avatar_url":"https://github.com/shell-nlp.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003ch1 align=\"center\"\u003eDeepClaw\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Python\" src=\"https://img.shields.io/badge/Python-3.12%2B-3776AB?style=flat-square\u0026logo=python\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"FastAPI\" src=\"https://img.shields.io/badge/FastAPI-0.115-009688?style=flat-square\u0026logo=fastapi\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"LangGraph\" src=\"https://img.shields.io/badge/LangGraph-Agent-1C3C3C?style=flat-square\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Next.js\" src=\"https://img.shields.io/badge/Next.js-15-000000?style=flat-square\u0026logo=nextdotjs\u0026logoColor=white\"\u003e\u003c/a\u003e\n  \u003ca href=\"#\"\u003e\u003cimg alt=\"Elasticsearch\" src=\"https://img.shields.io/badge/Elasticsearch-8.x-005571?style=flat-square\u0026logo=elasticsearch\u0026logoColor=white\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"#快速开始\"\u003e快速开始\u003c/a\u003e\n  ·\n  \u003ca href=\"#核心能力\"\u003e核心能力\u003c/a\u003e\n  ·\n  \u003ca href=\"#界面预览\"\u003e界面预览\u003c/a\u003e\n  ·\n  \u003ca href=\"#api-接口\"\u003eAPI 接口\u003c/a\u003e\n  ·\n  \u003ca href=\"#配置说明\"\u003e配置说明\u003c/a\u003e\n  ·\n  \u003ca href=\"#项目结构\"\u003e项目结构\u003c/a\u003e\n\u003c/p\u003e\n\nDeepClaw 是一个面向二次开发的智能体服务。项目把通用 Agent、RAG 知识库、技能管理、渠道接入、MCP 配置和静态前端整合到同一个 FastAPI 服务中，适合快速搭建企业知识问答、自动化助手、内部 Copilot 和多工具智能体应用。\n\n## 核心能力\n\n| 能力 | 说明 |\n|------|------|\n| 通用 Agent | 基于 LangGraph / DeepAgents 构建，支持工具调用、SSE 流式输出、MCP 配置透传 |\n| RAG 知识库 | 支持知识库创建、文档上传、切片查看、图检索 RAG 和独立 RAG 问答 |\n| 多模态输入 | 通用接口 `query` 支持纯文本与图文混合结构 |\n| 技能管理 | 支持技能列表、上传和删除 |\n| 渠道接入 | 内置飞书、钉钉、微信 ClawBot 路由和会话管理 |\n| 多执行后端 | 支持 `local_shell`、`store`、`sandbox` 三种执行模式 |\n| 前端界面 | Next.js + React 聊天 UI，构建后由 FastAPI 的 `/` 统一托管 |\n| 可观测性 | 可选接入 Phoenix tracing、Postgres 长期记忆和 Tavily 搜索 |\n\n## 界面预览\n\n以下界面覆盖项目当前的主要工作流，包括聊天、人工确认、知识库、技能管理、MCP 管理、渠道管理和用户隔离。\n\n### 聊天主界面\n\n![聊天界面](assets/img/chat.png)\n\n统一承载 Agent 对话、工具调用流式输出和核心交互入口。\n\n### Human in the Loop 人工确认\n\n![Human in the Loop](assets/img/human_in_the_loop.png)\n\n展示工具调用进入人工确认后的审批与参数编辑流程。\n\n### 知识库管理\n\n![知识库管理](assets/img/knowledge_base.png)\n\n用于查看知识库列表、知识详情、文档分页和切片明细。\n\n### 技能管理\n\n![技能管理](assets/img/skill_management.png)\n\n用于上传、删除和维护工作区技能目录。\n\n### MCP 管理\n\n![MCP 管理](assets/img/mcp_management.png)\n\n用于维护 MCP 配置，并控制通用 Agent 请求是否附带 MCP 服务定义。\n\n### 渠道管理\n\n![渠道管理](assets/img/channels_management.png)\n\n用于管理飞书、钉钉、微信 ClawBot 渠道接入、用户绑定和会话回复模式。\n\n### 用户管理\n\n![用户管理](assets/img/user_management.png)\n\n用于切换和维护不同用户身份，隔离对话、知识库和渠道数据。\n\n## 技术栈\n\n| 模块 | 技术 |\n|------|------|\n| 后端 | FastAPI, LangGraph, DeepAgents, LangChain |\n| RAG | Elasticsearch, Dense Vector, BM25, Graph RAG |\n| 前端 | Next.js 15, React 19, TypeScript |\n| 执行后端 | Local Shell, Store Backend, OpenSandbox |\n| 可选组件 | Phoenix, Tavily, PostgresStore |\n| 包管理 | uv, pnpm |\n\n## 项目结构\n\n```text\ndeepclaw/\n├── deepclaw/\n│   ├── agents/              # 通用 Agent / RAG Agent 组装、上下文与状态\n│   ├── backend/             # 执行后端相关实现\n│   ├── common/              # Elasticsearch、Graph RAG、文本切分等通用实现\n│   ├── middleware/          # 业务开关、RAG 注入、MCP、工具搜索等中间件\n│   ├── patch/               # 第三方库补丁与适配\n│   ├── tools/               # 天气、网页抓取、检索、定时任务等工具\n│   ├── web_backend/         # FastAPI Web 应用层与所有 Web 功能目录\n│   ├── main.py              # 主启动入口\n│   └── settings.py          # 环境变量配置\n├── frontend/                # Next.js 前端\n├── .deepclaw/               # 运行时工作区、技能目录、渠道数据库等\n├── assets/                  # 截图和 Elasticsearch 插件\n└── docker-compose.yml       # PostgreSQL / Elasticsearch / Phoenix\n```\n\n## 快速开始\n\n### 1. 环境要求\n\n| 场景 | 依赖 |\n|------|------|\n| 仅运行后端和已构建前端 | Python `\u003e= 3.12`、`uv`、Docker / Docker Compose |\n| 开发或重新构建前端 | 额外需要 Node.js `\u003e= 18`、`pnpm` |\n\n如果仓库里的 `frontend/out` 已经存在，且你不修改前端代码，可以直接跳过前端安装和构建步骤。\n\n### 2. 启动依赖服务\n\n```bash\ndocker-compose up -d postgresql elasticsearch\n```\n\n如需 Phoenix 观测：\n\n```bash\ndocker-compose up -d phoenix\n```\n\nPhoenix 控制台默认地址：`http://localhost:6006`\n\n### 3. 初始化后端\n\n```bash\ncp .env.example .env\nuv sync --dev\n```\n\n如果要启用 OpenSandbox：\n\n```bash\nuv sync --dev --extra opensandbox\n```\n\n### 4. 配置 `.env`\n\n至少填入：\n\n```dotenv\nOPENAI_API_KEY=your-api-key\nOPENAI_API_BASE=http://localhost:8082/v1\nCHAT_MODEL_NAME=qwen3\nEMBEDDING_MODEL_NAME=qwen3-embedding\nES_URL=http://localhost:9200\nES_URSR=elastic\nES_PWD=elastic@2024\n```\n\n### 5. 启动主服务\n\n统一从 `main` 入口启动：\n\n```bash\nuv run python -m deepclaw.main\n```\n\n服务启动后：\n\n- 前端页面：`http://localhost:7869/`\n- Agent SSE：`POST /api/agent/general_api`\n- Agent AG-UI：`POST /api/agent/ag_ui`\n- RAG SSE：`POST /api/rag/general_api`\n- Channels API：`/api/channels/*`\n\n### 6. 前端开发\n\n仅在你需要开发或重新构建前端时执行：\n\n```bash\ncd frontend\npnpm install\npnpm dev\n```\n\n开发模式地址：`http://localhost:3000`\n\n构建静态前端并交给后端托管：\n\n```bash\ncd frontend\npnpm build\n```\n\n## API 接口\n\n### Agent\n\n| 方法 | 路径 | 协议 | 用途 |\n|------|------|------|------|\n| `POST` | `/api/agent/ag_ui` | AG-UI | Agent 前端协议接口 |\n| `POST` | `/api/agent/general_api` | SSE | 通用 Agent 流式接口 |\n| `POST` | `/api/agent/skills/list` | REST | 技能列表 |\n| `POST` | `/api/agent/skills/upload` | REST | 上传技能 zip |\n| `POST` | `/api/agent/skills/delete` | REST | 删除技能 |\n\n### RAG\n\n| 方法 | 路径 | 协议 | 用途 |\n|------|------|------|------|\n| `POST` | `/api/rag/general_api` | SSE | RAG 流式问答 |\n| `POST` | `/api/rag/knowledge-bases/list` | REST | 知识库分页列表 |\n| `POST` | `/api/rag/knowledge-bases/create` | REST | 创建知识库 |\n| `POST` | `/api/rag/knowledge-bases/detail` | REST | 知识库详情 |\n| `POST` | `/api/rag/knowledge-bases/update` | REST | 更新知识库 |\n| `POST` | `/api/rag/knowledge-bases/delete` | REST | 删除知识库 |\n| `POST` | `/api/rag/knowledge-bases/bulk-delete` | REST | 批量删除知识库 |\n| `POST` | `/api/rag/knowledge-bases/documents/list` | REST | 文档分页列表 |\n| `POST` | `/api/rag/knowledge-bases/documents/detail` | REST | 文档切片详情 |\n| `POST` | `/api/rag/knowledge-bases/documents/upload` | REST | 上传文档 |\n| `POST` | `/api/rag/knowledge-bases/documents/update` | REST | 更新文档展示名 |\n| `POST` | `/api/rag/knowledge-bases/documents/delete` | REST | 删除文档 |\n| `POST` | `/api/rag/knowledge-bases/documents/bulk-delete` | REST | 批量删除文档 |\n\n### Channels\n\n| 方法 | 路径 | 协议 | 用途 |\n|------|------|------|------|\n| `POST` | `/api/channels/feishu/events` | REST | 飞书事件入口 |\n| `POST` | `/api/channels/dingtalk/events` | REST | 钉钉事件入口 |\n| `POST` | `/api/channels/weixin-clawbot/qrcode` | REST | 获取微信 ClawBot 登录二维码 |\n| `GET` | `/api/channels/weixin-clawbot/qrcode/status` | REST | 查询二维码状态 |\n| `POST` | `/api/channels/weixin-clawbot/users/{user_id}/qrcode` | REST | 生成用户绑定二维码 |\n| `GET` | `/api/channels/weixin-clawbot/users` | REST | 列出已绑定用户 |\n| `DELETE` | `/api/channels/weixin-clawbot/users/{user_id}` | REST | 删除绑定 |\n| `GET` | `/api/channels/sessions` | REST | 列出渠道会话 |\n| `PATCH` | `/api/channels/sessions/{session_id}` | REST | 更新会话回复模式 |\n\n## 使用示例\n\n### 通用 Agent 问答\n\n```bash\ncurl -N -X POST http://localhost:7869/api/agent/general_api \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"帮我总结一下今天的工作安排\",\n    \"session_id\": \"demo-session\",\n    \"user_id\": \"demo-user\",\n    \"internet_search\": false,\n    \"deep_thinking\": false\n  }'\n```\n\n### 多模态 Agent 输入\n\n```bash\ncurl -N -X POST http://localhost:7869/api/agent/general_api \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": [\n      { \"type\": \"text\", \"text\": \"这张图片里有什么？\" },\n      {\n        \"type\": \"image\",\n        \"url\": \"https://example.com/demo.jpg\",\n        \"mime_type\": \"image/jpeg\"\n      }\n    ],\n    \"session_id\": \"multi-modal-session\",\n    \"user_id\": \"demo-user\"\n  }'\n```\n\n### 创建知识库\n\n```bash\ncurl -X POST http://localhost:7869/api/rag/knowledge-bases/create \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"user_id\": \"demo-user\",\n    \"name\": \"产品文档\",\n    \"description\": \"示例知识库\"\n  }'\n```\n\n### 上传文档\n\n```bash\ncurl -X POST http://localhost:7869/api/rag/knowledge-bases/documents/upload \\\n  -F \"user_id=demo-user\" \\\n  -F \"knowledge_base_id=\u003cknowledge_base_id\u003e\" \\\n  -F \"files=@./demo.pdf\"\n```\n\n### 调用 RAG 流式问答\n\n`index_name` 和 `graph_name` 可从知识库详情返回值中的 `passage_index`、`index_prefix` 获取。\n\n```bash\ncurl -N -X POST http://localhost:7869/api/rag/general_api \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"query\": \"这份文档的核心结论是什么？\",\n    \"session_id\": \"rag-session\",\n    \"user_id\": \"demo-user\",\n    \"index_name\": \"kb_xxx_passages\",\n    \"graph_name\": \"kb_xxx\"\n  }'\n```\n\n## 配置说明\n\n### 必填环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `OPENAI_API_BASE` | OpenAI-compatible LLM API 地址 |\n| `OPENAI_API_KEY` | LLM API 密钥 |\n| `CHAT_MODEL_NAME` | 聊天模型名称 |\n| `EMBEDDING_MODEL_NAME` | 向量模型名称 |\n| `ES_URL` | Elasticsearch 地址 |\n| `ES_URSR` | Elasticsearch 用户名 |\n| `ES_PWD` | Elasticsearch 密码 |\n\n### 常用可选环境变量\n\n| 变量 | 说明 |\n|------|------|\n| `BACKEND_TYPE` | 执行后端：`local_shell` / `store` / `sandbox` |\n| `PG_DATABASE_URL` | 启用 PostgresStore 长期记忆 |\n| `TAVILY_API_KEY` | 启用联网搜索工具 |\n| `USE_TOOL_SEARCH` | 启用延迟工具搜索 |\n| `USE_COPILOTKIT` | 启用 CopilotKit 中间件 |\n| `PHOENIX_COLLECTOR_ENDPOINT` | 启用 Phoenix tracing |\n| `AUTH_ADMIN_EMAIL` | 默认管理员邮箱 |\n| `AUTH_ADMIN_PASSWORD` | 默认管理员密码 |\n| `AUTH_TOKEN_EXPIRE_DAYS` | 登录态有效期天数 |\n| `CHANNEL_AGENT_API_URL` | 渠道网关调用 Agent 的地址 |\n| `WEIXIN_CLAWBOT_*` | 微信 ClawBot 相关配置 |\n\n## 常见说明\n\n- 后端会直接挂载 `frontend/out`。如果该目录已经存在，纯运行场景不需要安装 Node.js 和 pnpm。\n- 前端修改后，必须重新执行 `pnpm build`，后端 `/` 才会提供最新页面。\n- 默认工作区位于 `.deepclaw/workspace`。\n- 渠道模块默认把 SQLite 数据库写入 `.deepclaw/channels.db`。\n- 如果 `frontend/out` 不存在，后端仍可提供 API，但 `/` 不会挂载前端页面。\n\n## License\n\nApache-2.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshell-nlp%2Fdeepclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshell-nlp%2Fdeepclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshell-nlp%2Fdeepclaw/lists"}