AgentClaw

你的 24/7 AI 指挥官——理解意图、规划任务、调度工具、记住一切的智能调度中心。

AgentClaw 是一个指挥官级别的个人 AI 助理，同时也是一个 Agent 托管平台（Hive）。它自己不写代码（调用编程技能），自己不搜索（调用搜索技能），但它理解你的意图、规划复杂任务、调度合适的工具和技能，并通过 Web UI / Telegram / WhatsApp / 钉钉 / 飞书 / QQ 全天候待命。

Hive 模式下，任何人都可以创建、配置、发布独立 Agent，获得即用的 API 端点——定义 Soul，选择 Tools，导入知识，拿到 Key，上线。每个 Agent 拥有独立的记忆空间、工具白名单、技能黑名单、知识库和 API Key。

架构

你（老板）/ 外部系统（API 调用）
  │
  ▼
AgentClaw Hive（Agent 托管平台）
  │
  ├── Agent 1 (Soul + Tools + Skills + Memory + Knowledge + API Key)
  ├── Agent 2 ...
  ├── Agent N ...  ← 完全隔离，独立认证
  │
  ├── LLM 提供商 (Claude, OpenAI, Gemini, DeepSeek, Kimi, Qwen, Doubao...)
  ├── 智能路由 (自动故障切换, Fast Provider 路由)
  ├── 核心工具 (shell, file_read/write/edit, glob, grep, ask_user, web_fetch, web_search, context_search, compact)
  ├── 条件工具 (send_file, schedule, remember, use_skill, sandbox, subagent...)
  ├── 记忆 (对话历史 + 长期记忆 + 自动压缩 + namespace 隔离)
  ├── 技能 x12 (gws-calendar/gmail/drive/sheets/tasks, pdf, docx, xlsx, pptx, bilingual-subtitle...)
  ├── 子代理 (并行任务派发与汇总)
  ├── 工具钩子 (before/after 拦截 + allow/deny 策略)
  └── MCP 集成 (外部工具服务器)

技术栈

• 语言: TypeScript monorepo (pnpm + Turborepo)
• LLM: Claude + OpenAI 兼容 (DeepSeek/Kimi/Qwen/Doubao) + Gemini
• 存储: SQLite (better-sqlite3)
• 网关: Fastify HTTP + WebSocket + Telegram Bot + WhatsApp Bot + 钉钉 + 飞书 + QQ Bot + 企业微信
• 前端: React 19 + Vite (Light/Dark 主题)
• 桌面: Tauri v2 (Rust) + Bun sidecar，三平台安装包
• 调度: Cron 定时任务 + 心跳检查
• 构建: tsup (ESM) + Turborepo

项目结构

agentclaw/
├── packages/
│   ├── types/       — 共享类型定义
│   ├── providers/   — LLM 适配器 (Claude, OpenAI兼容, Gemini) + FailoverProvider
│   ├── tools/       — 工具注册表 + 分层内置工具 + MCP 客户端
│   ├── memory/      — SQLite 持久化 (会话/消息/记忆/Traces/Token日志)
│   ├── core/        — Agent Loop + Orchestrator + ContextManager + SkillRegistry
│   ├── gateway/     — Fastify HTTP/WS + 多渠道 Bot + 定时调度 + TaskManager
│   ├── cli/         — 终端交互式对话
│   ├── web/         — React 19 + Vite 前端
│   └── desktop/     — Tauri v2 桌面客户端 (Windows/macOS/Linux)
├── skills/          — 12 个技能定义 (SKILL.md)
├── docs/            — 架构文档 + 路线图 + 技术文章系列
└── data/            — 运行时数据 (部分 gitignored)
    └── agents/      — Agent 人格配置 (config.json + SOUL.md)

快速开始

桌面安装

从 Releases 下载对应平台安装包：

• Windows: .exe (NSIS 安装包，内嵌 WebView2)
• macOS: .dmg
• Linux: .deb

启动后通过 Setup Wizard 配置 LLM Provider 即可使用。

一键安装（推荐）

Linux、macOS 和 Termux 可用一条命令完成安装、模型配置、构建和启动：

curl -fsSL https://raw.githubusercontent.com/vorojar/AgentClaw/master/scripts/install.sh | bash

安装器会自动检查并安装基础依赖（git、curl、Node.js、pnpm、ffmpeg、Python/构建工具），随后引导选择模型提供商并填写 API Key。完成后打开 http://127.0.0.1:3100 即可开始对话。

默认安装只启用核心对话能力，避免首次安装拉取 Chromium、SearXNG、Redis 等重依赖。搜索引擎、消息渠道、浏览器自动化等高级能力可在安装后按需配置。

Docker 部署

git clone https://github.com/vorojar/AgentClaw.git
cd AgentClaw
cp .env.example .env
# 编辑 .env，至少填入一个 LLM API key

docker compose up -d

打开 http://localhost:3100 即可使用。

Docker 默认只启动 AgentClaw 核心服务，不再自动启动本地搜索。需要本地 SearXNG 时：

docker compose --profile search up -d

随后在 Settings > Search 配置 http://searxng:8080，或使用 Serper / Querit / Custom 搜索 API。

浏览器自动化默认关闭。需要 browser_cdp 时请自行安装 Chrome/Chromium，或用 --build-arg INSTALL_BROWSER=true 构建 Docker 镜像，并设置：

AGENTCLAW_ENABLE_BROWSER_CDP=true

手动部署

前置要求： Node.js >= 20, pnpm >= 9

git clone https://github.com/vorojar/AgentClaw.git
cd AgentClaw
pnpm install
npm run build
cp .env.example .env
# 编辑 .env，至少填入一个 LLM API key

npm run start

打开 http://localhost:3100

配置

所有配置通过环境变量，参见 .env.example 获取完整列表。

最低要求： 一个 LLM API key（ANTHROPIC_API_KEY、OPENAI_API_KEY 或 GEMINI_API_KEY）。

其他启动方式

npm run start:web    # Web UI 开发服务器（热更新）
npm run cli          # 终端交互模式

核心功能

Hive — Agent-as-a-Service

创建独立 Agent，每个 Agent 拥有完全隔离的配置和运行环境：

Agent API 端点：

POST /api/v1/agents/:id/chat              # 无状态对话
POST /api/v1/agents/:id/chat/stream       # SSE 流式
POST /api/v1/agents/:id/sessions          # 创建会话
POST /api/v1/agents/:id/sessions/:sid/chat # 会话内对话

多通道接入

• Web UI — 现代化聊天界面，Light/Dark 主题，文件上传/拖拽，视频/音频播放器嵌入，多模态图片理解
• Telegram Bot — 支持文字/图片/文档/语音/视频消息
• WhatsApp Bot — 自聊模式，QR 扫码认证
• QQ Bot — QQ 开放平台官方 API v2，WebSocket 模式
• 钉钉 — Stream 模式，无需公网 IP
• 飞书 — WebSocket 模式，无需公网 IP
• 企业微信 — WebSocket 模式，@wecom/aibot-node-sdk
• REST API — 会话、消息、Traces、Token 日志、配置、记忆

模型 Failover + 错误分类

配置多个 LLM API Key 时自动按优先级尝试。7 类错误自动分类（auth/quota/rate_limit/overloaded/server_error/config/network），按类型决定冷却时间（429→60s, 503→15s），冷却中的模型降优先级而非移除。三振升级机制检测模型卡住（连续 3 次相似输出），自动注入策略变更提示。

安全纵深防御

• Shell 沙箱：拦截不可逆破坏性命令 + printenv/env + 元数据服务地址
• SSRF 防护：web_fetch 拦截内网地址（127/10/172.16/192.168/169.254）
• 路径遍历防护：file_read 正则黑名单拦截 .env.*/SSH 密钥/proc/sys 系统路径
• Trace 混淆：工具结果写入 trace 前通过 env-obfuscator 替换敏感环境变量值
• Subagent 封堵：工具黑名单 + sendFile/saveMemory 回调不透传子代理
• MCP 消毒：外部 MCP server 返回内容检测 prompt injection 并标记
• Memory 审查：remember 写入前扫描 prompt injection（含中文）、隐形 unicode、凭证窃取
• Docker 沙箱：sandbox 工具在容器内执行，资源限制（512MB/1CPU），超时控制
• 系统提示词裁剪：agent 有工具白名单时，自动移除引用不可用工具的规则

Agent Handoff（代理交接）

对话中 Agent 可通过 handoff 工具将对话交给更合适的专家 Agent 继续处理。交接后保留完整对话历史，目标 Agent 使用自己的人格、模型和工具集继续响应。最多 3 次连续交接防止循环。

子代理编排

subagent 工具可派生独立子 agent 并行执行任务，拥有独立 agent-loop 和会话上下文。支持 spawn/spawn_and_wait/result/kill/list 操作，mode: "explore" 只读模式仅加载搜索/阅读工具子集。安全机制：工具黑名单（6 个危险工具始终禁止）、IterationBudget 父子共享迭代预算池防止无限消耗。

任务管理（TaskManager）

完整的任务生命周期管理引擎：

• 捕获 — 自然语言创建任务，LLM 自动解析标题、优先级、执行者
• 分诊 — 自动判断 agent/human 执行者，按优先级排队
• 执行 — 队列调度，自动执行 agent 任务，记录 trace
• 决策 — 需要用户拍板时推送决策卡片，heartbeat 定期提醒（不消耗 LLM token）
• 每日简报 — 定时推送，汇总待办/进行中/等决策任务

长期记忆

自动从对话中提取事实、偏好、实体、经验，去重存储，上下文中自动注入相关记忆。按 agent 命名空间隔离，Web UI 支持按 agent 筛选管理。

上下文压缩（多层流水线）

• L6 观察压缩：旧 tool_result 智能提取错误行/状态/JSON 关键字段（80-95% token 节省）
• L2+L5 基础压缩：空白规范化 + JSON minify，所有 tool_result 自动应用
• 三层摘要瀑布：LLM 正常 → LLM 低温 → 确定性截断（永远成功）
• Tool pair 保护：压缩后自动修复孤立的 tool_call/tool_result（block 级清理）
• Frozen Snapshot：动态上下文每 session 只构建一次，最大化 prompt cache 命中率

TTS 语音回复

用户发语音时 AI 以语音回复，支持 edge-tts 和 vibevoice 引擎。

工具系统

分层加载架构——Gateway 加载全部工具，CLI 仅加载核心工具：

技能系统

LLM 自主判断是否需要技能，通过 use_skill 工具调用。支持在 Web UI 中启用/禁用单个技能，以及从 GitHub 或 zip 导入社区技能。12 个内置技能：

Artifacts 实时预览

代码块支持实时预览，点击 Preview 按钮即可在聊天中直接渲染：

生成的 HTML 文件（/files/*.html）显示为可点击的预览卡片，全屏覆盖层浏览。

MCP 集成

支持通过 data/mcp-servers.json 配置外部 MCP (Model Context Protocol) 工具服务器，支持 stdio 和 HTTP 传输。

环境变量

常见问题

确保 .env 中至少配置了一个有效的 API key（三选一）：

ANTHROPIC_API_KEY=sk-ant-xxx    # Claude 系列
OPENAI_API_KEY=sk-xxx           # GPT 系列 / OpenAI 兼容
GEMINI_API_KEY=AIzaSy-xxx       # Gemini 系列

检查：key 前后无多余空格/引号，key 未过期，Docker 部署时 .env 在 docker-compose.yml 同级目录。

# 确认容器正在运行
docker compose ps

# 检查日志
docker compose logs gateway

# 确认端口映射（默认 3100）
# 云服务器需放行防火墙
sudo ufw allow 3100

已修复（v1.5.17+）。如果仍遇到，检查 data/config.json 中 toolPermissions 是否有 deny 规则。被禁用的工具会返回明确的 "Do NOT retry" 提示，agent 应自动切换替代方案。

这是上下文压缩触发的正常行为。系统会在 token 超限时自动压缩旧消息。主动压缩：让 agent 调用 compact 工具，或在 Web UI 中点击压缩按钮。压缩后 tool_result 保留关键信息（错误行/状态/JSON 字段），80-95% token 节省。

Web UI

现代化 Web 界面，支持 Light/Dark 主题切换：

• 聊天 — WebSocket 流式输出、工具调用卡片、文件上传/拖拽、视频/音频播放器、Agent 选择器、Agent 指示条
• 任务 — Today/All Tasks/Decisions/Automations 四标签页
• 代理 — Agent 详情页：Profile / Tools & Skills / Knowledge / API 四个 Tab，测试按钮跳转 ChatPage
• 记忆 — 按 Agent 命名空间筛选、按类型和重要性排序
• 设置 — LLM Provider 配置、用量统计、外观/主题/语言、渠道、Traces

文档

• Building AI Agent Frameworks — 10 篇技术系列文章（By Rosibo & Claude）
• Hive 设计文档 — Agent-as-a-Service 平台架构与路线图
• 架构设计
• 路线图
• 更新日志

License

MIT