简介

AgentHub 是一个全功能的 AI Agent Web UI，可本地或远程部署，让你随时随地（手机、电脑）管理和使用 AI Agent 会话。支持 Claude、Gemini、Codex 多种 AI 引擎，并提供飞书 IM 集成、多用户管理、工具安全守卫等企业级特性。

功能特性

核心对话

• Claude Agent 对话 — 基于 @anthropic-ai/claude-agent-sdk，支持流式响应、工具调用、会话续接
• Gemini Shell — node-pty 驱动 Gemini CLI，xterm.js 渲染真实终端体验
• Codex Shell — node-pty 驱动 Codex CLI，xterm.js 渲染，独立会话隔离
• WebSocket 实时通信 — 前后端通过 WebSocket 双向通信，响应实时推送

项目与文件管理

• 项目管理 — 自动发现 Agent 会话，按项目分组，支持重命名、删除
• 文件浏览器 — 交互式文件树，支持展开/折叠导航
• 文件编辑器 — CodeMirror 6 驱动，多语言语法高亮、实时编辑保存
• MCP 服务器支持 — 通过 UI 添加、管理自定义 MCP 服务器，自动同步到 Codex

多用户与权限

• 多用户系统 — 注册/登录，JWT 认证，每用户数据完全隔离（独立 UUID 目录）
• 三级角色 — super_admin（首个注册用户）、admin（受限管理员）、user（普通用户）
• 限额管理 — 按用户设置每日使用限额，管理员面板实时查看用量
• 邮箱域名白名单 — 限制注册邮箱域名范围

飞书 IM 集成

• WebSocket 长连接 — 通过 @larksuiteoapi/node-sdk 接收飞书消息
• 单聊对话 — 在飞书直接与 AI Agent 对话
• 工具审批卡片 — Agent 执行危险操作时，飞书推送审批卡片
• 语音转文字 — 支持语音消息（需配置 ffmpeg + Whisper）
• 文件/图片发送 — Agent 可将生成文件自动发送到飞书聊天

安全

• 工具安全守卫（Tool Guard） — 双层检测：正则规则快速拦截 + LLM 兜底审查
• 路径隔离 — 阻止访问用户目录之外的文件系统路径
• 危险命令拦截 — 阻止 rm -rf、系统文件修改、全局包安装等高危操作

Agent 商店

• 系统 Agent 仓库 — 发布、安装、管理预置 Agent
• 版本管理 — 支持 Agent 版本控制与更新
• 管理员审核 — Agent 提交需管理员审核后才能上架

其他

• 图片持久化 — 聊天图片 SHA-256 去重存储，30 天自动清理
• 计费统计 — 按模型精确计算 token 用量和费用
• 响应式设计 — 桌面、平板、手机全端适配，支持添加到主屏幕

快速开始

环境要求

• Node.js v20 或更高版本
• Claude Code CLI 已安装并配置

一键运行（推荐）

无需安装，直接运行：

npx agenthub

服务启动后访问 http://localhost:3001（或你配置的端口）。

全局安装

npm install -g agenthub
agenthub

更新到最新版本：

agenthub update

CLI 命令

| 命令 / 选项 | 简写 | 说明 | |------------|------|------| | agenthub | | 启动服务（默认） | | agenthub start | | 显式启动服务 | | agenthub status | | 显示配置和数据目录信息 | | agenthub update | | 更新到最新版本 | | agenthub help | | 显示帮助信息 | | agenthub version | | 显示版本信息 | | --port <port> | -p | 指定端口（默认：3001） | | --database-path <path> | | 指定数据库存储路径 |

示例：

agenthub -p 8080          # 在 8080 端口启动
agenthub status           # 查看当前配置

后台服务（生产环境推荐）

使用 PM2 作为进程管理器：

npm install -g pm2

# 启动后台服务
pm2 start agenthub --name "agenthub"

# 在指定端口启动
pm2 start agenthub --name "agenthub" -- --port 8080

# 开机自启
pm2 startup
pm2 save

本地开发

# 克隆仓库
git clone [email protected]:share/agenthub.git
cd agenthub

# 安装依赖
npm install

# 配置环境变量
cp .env.example .env
# 编辑 .env 填写所需配置

# 开发模式（React 热重载 + Node 服务器）
npm run dev

其他开发命令：

npm run build    # 生产构建
npm run start    # 构建 + 启动服务器
npm run server   # 仅启动 Node 服务器
npm run client   # 仅启动 Vite dev 服务器

环境变量配置

在 .env 文件中配置以下变量：

基础配置

| 变量 | 说明 | |------|------| | PORT | 服务端口，默认 3001 | | JWT_SECRET | JWT 签名密钥（必填） | | ANTHROPIC_API_KEY | Anthropic API Key |

飞书集成（可选）

| 变量 | 说明 | |------|------| | FEISHU_APP_ID | 飞书应用 App ID | | FEISHU_APP_SECRET | 飞书应用 App Secret | | FEISHU_MENU_KEY_MAP | JSON 格式，event_key → 斜杠命令映射 | | FEISHU_CARD_*_ID | 各类消息卡片模板 ID |

设置 FEISHU_APP_ID 和 FEISHU_APP_SECRET 即可自动启用飞书集成。

语音转文字（可选，需飞书集成）

| 变量 | 说明 | |------|------| | WHISPER_* | Whisper 语音识别相关配置 |

工具安全守卫（可选）

| 变量 | 说明 | 默认值 | |------|------|--------| | TOOL_GUARD_ENABLED | 总开关 | false | | TOOL_GUARD_LLM_ENABLED | LLM 审查开关 | false | | TOOL_GUARD_LLM_MODEL | LLM 审查模型 | gemini-3.1-flash-lite-preview | | TOOL_GUARD_LLM_TIMEOUT_MS | LLM 超时时间（毫秒） | 5000 | | TOOL_GUARD_VERBOSE | 详细日志 | false |

LLM 通用配置（Tool Guard LLM 审查用）

| 变量 | 说明 | |------|------| | OPENAI_API_KEY | OpenAI 兼容 API Key | | OPENAI_BASE_URL | OpenAI 兼容 API Base URL |

架构概览

┌──────────────────────┐    ┌──────────────────────┐    ┌──────────────────────┐
│  前端 (React + Vite)  │◄──►│  后端 (Express + WS)  │◄──►│  AI 引擎集成          │
│                      │    │                      │    │  Claude / Gemini     │
│  - ChatInterface     │    │  - claude-sdk.js     │    │  / Codex             │
│  - GeminiShell       │    │  - WebSocket 路由     │    │                      │
│  - CodexShell        │    │  - REST API          │    └──────────────────────┘
│  - CodeEditor        │    │  - SQLite (DB)       │
│  - AdminPanel        │    │  - Tool Guard        │    ┌──────────────────────┐
└──────────────────────┘    │  - 飞书 IM 服务       │◄──►│  飞书 IM              │
                            └──────────────────────┘    │  (长连接 WS)          │
                                                        └──────────────────────┘

技术栈

| 层级 | 技术 | |------|------| | 前端框架 | React 18 + Vite 7 | | 样式 | Tailwind CSS 3.4 | | 文件编辑器 | CodeMirror 6 | | 终端 | xterm.js | | 后端框架 | Node.js 20+ + Express 4 | | 实时通信 | WebSocket (ws) | | 数据库 | better-sqlite3 | | 终端进程 | node-pty | | AI SDK | @anthropic-ai/claude-agent-sdk | | 飞书 SDK | @larksuiteoapi/node-sdk |

工具设置

注意：所有 Agent 工具默认关闭，防止自动执行高风险操作。

开启工具步骤：

1. 点击侧边栏齿轮图标打开设置
2. 进入"工具设置"
3. 按需开启所需工具
4. 设置会自动保存

建议从基础工具开始，按需逐步开启。

常见问题

无项目显示

• 确认至少初始化了一个项目
• 检查 ~/.claude/projects/ 目录是否存在且有读取权限

文件浏览器无法加载

• 检查项目目录权限（ls -la）
• 确认项目路径存在且可访问
• 查看服务器控制台日志获取详细错误信息

飞书集成不工作

• 确认 FEISHU_APP_ID 和 FEISHU_APP_SECRET 已正确设置
• 检查飞书应用是否已开启事件订阅
• 确认机器人已被添加到对应群/单聊

许可证

MIT License — 详见 LICENSE 文件。