ClawPort UI 调研报告
notes/research/github/clawport-ui-research-20260310.md
Port 8777
---
title: ClawPort UI 调研报告
category: research/github
source_type: github
created_by: xiaomeixia
status: archived
migrated_from: agent-notes/xiaomeixia/research/github/clawport-ui-research-20260310.md
tags: []
---
# ClawPort UI 调研报告
**来源**: https://github.com/JohnRiceML/clawport-ui
**调研时间**: 2026-03-10
**调研人**: 小美虾 🦐
---
## 📌 一句话总结
**ClawPort UI**: OpenClaw 的开源 AI Agent 指挥中心 —— 提供组织架构图、Agent 直聊、看板、Cron 监控、成本追踪、活动控制台和记忆浏览器等功能的一站式仪表板。
---
## 🎯 核心价值
> "Open-source AI agent command center for Claude Code agent teams. Built on OpenClaw."
**核心功能**:
- ✅ **无需额外 API 密钥** - 所有 AI 请求通过 OpenClaw 网关路由
- ✅ **可视化 Agent 团队** - 组织架构图展示层级关系
- ✅ **实时交互** - 支持文本、图像、语音、文件的多模态聊天
- ✅ **任务管理** - Kanban 看板管理跨 Agent 工作
- ✅ **监控告警** - Cron 任务状态实时监控
- ✅ **成本分析** - Token 使用和成本追踪
---
## 🚀 快速开始
### 前置条件
需要运行中的 OpenClaw 实例：
```bash
# 安装 OpenClaw
curl -fsSL https://openclaw.ai/install.sh | bash
# 运行 onboarding 向导
openclaw onboard --install-daemon
# 验证网关运行
openclaw gateway status
```
### 安装 ClawPort
```bash
# 安装 CLI 工具 (注意包名是 clawport-ui)
npm install -g clawport-ui
# 自动检测 OpenClaw 配置并写入 .env.local
clawport setup
# 启动仪表板
clawport dev
```
访问 http://localhost:3000
### 源码安装
```bash
git clone https://github.com/JohnRiceML/clawport-ui.git
cd clawport-ui
npm install
npm run setup
npm run dev
```
---
## 📊 核心功能
### 1. 🏢 组织架构图 (Org Map)
- **交互式组织图** - 展示整个 Agent 团队的层级关系
- **状态显示** - Cron 状态、关系一目了然
- **技术栈** - React Flow + 自动布局
**适用场景**:
- 查看多 Agent 团队的层级结构
- 快速了解 Agent 职责分工
- 监控 Agent 运行状态
---
### 2. 💬 聊天 (Chat)
- **流式文本聊天** - 实时流式响应
- **图像附件** - 支持视觉识别
- **语音消息** - 波形播放
- **文件附件** - 拖拽上传
- **剪贴板粘贴** - 快速分享
- **本地持久化** - 聊天记录保存
**适用场景**:
- 与特定 Agent 直接对话
- 发送图片/文件进行分析
- 语音消息交互
---
### 3. 📋 看板 (Kanban)
- **任务看板** - 管理跨 Agent 工作
- **拖拽卡片** - 直观的任务管理
- **Agent 分配** - 指定任务负责人
- **聊天上下文** - 关联对话历史
**适用场景**:
- 多 Agent 协作任务管理
- 项目进度跟踪
- 任务优先级排序
---
### 4. ⏰ Cron 监控 (Cron Monitor)
- **实时状态** - 所有定时任务状态
- **状态过滤** - 按状态筛选
- **错误置顶** - 错误任务优先显示
- **自动刷新** - 60 秒自动更新
- **详情展开** - 查看执行细节
**适用场景**:
- 监控定时任务执行情况
- 快速定位失败任务
- 查看任务执行历史
---
### 5. 💰 成本仪表板 (Cost Dashboard)
- **Token 使用分析** - 按 Cron 任务统计
- **每日成本图表** - 成本趋势可视化
- **模型分布** - 各模型使用占比
- **异常检测** - 发现异常消耗
- **周对比** - 周环比趋势
- **缓存节省** - Cache 命中率分析
**适用场景**:
- 追踪 AI 使用成本
- 优化高成本任务
- 预算规划
---
### 6. 📜 活动控制台 (Activity Console)
- **日志浏览器** - 历史事件查看
- **实时流** - 浮动实时日志组件
- **JSON 展开** - 点击展开原始 JSON
- **跨页持久化** - 实时流组件跨页面保持
**适用场景**:
- 调试 Agent 行为
- 查看系统事件
- 实时监控日志
---
### 7. 🧠 记忆浏览器 (Memory Browser)
- **团队记忆** - 查看团队共享记忆
- **长期记忆** - MEMORY.md 浏览
- **每日日志** - 按日期查看日志
- **Markdown 渲染** - 原生 Markdown 支持
- **JSON 高亮** - 语法高亮
- **搜索下载** - 搜索和下载功能
- **最佳实践** - 分类指南
**适用场景**:
- 回顾历史决策
- 学习 Agent 经验
- 知识管理
---
### 8. 👤 Agent 详情 (Agent Detail)
- **完整档案** - 每个 Agent 的详细资料
- **SOUL.md 查看器** - 查看 Agent 人格定义
- **工具列表** - 可用工具展示
- **层级关系** - 上下级关系
- **Cron 任务** - 关联的定时任务
- **语音 ID** - ElevenLabs 语音配置
- **直聊链接** - 一键开始对话
---
### 9. 🎨 主题系统
- **5 种主题** - Dark、Glass、Color、Light、System
- **CSS 变量** - 全部使用 CSS 自定义属性
- **即时切换** - 无需刷新即时生效
---
### 10. 🔍 自动发现
- **零配置** - 自动从 OpenClaw workspace 发现 Agent
- **无需配置文件** - 开箱即用
**扫描路径**:
- `$WORKSPACE_PATH/SOUL.md` - 根协调器
- `$WORKSPACE_PATH/IDENTITY.md` - 根 Agent 身份
- `$WORKSPACE_PATH/agents/*/SOUL.md` - 顶级 Agent
- `$WORKSPACE_PATH/agents/*/sub-agents/*.md` - 扁平子 Agent 文件
- `$WORKSPACE_PATH/agents/*/members/*.md` - 团队成员文件
- `$WORKSPACE_PATH/agents/*/*/SOUL.md` - 嵌套子目录 Agent
**忽略**:
- 没有 SOUL.md 的目录 (如 briefs/、数据文件)
- sub-agents/ 和 members/ 中的非 .md 文件
---
## 🏗️ 架构设计
### 数据流
```
Browser --> ClawPort (Next.js) --> OpenClaw Gateway (localhost:18789) --> Claude
| |
| Reads from: | AI Operations:
| - agents/ (SOUL.md) | - Text: /v1/chat/completions (SSE)
| - memory/ (team memory) | - Vision: chat.send (CLI)
| - cron list | - Audio: /v1/audio/transcriptions (Whisper)
```
**关键点**:
- 所有 AI 调用（聊天、视觉、TTS、转录）都通过网关路由
- 单一 Token，无需单独 API 密钥
- 本地读取 workspace 文件，无需网络请求
---
### 环境变量
| 变量 | 说明 | 获取方式 |
|------|------|----------|
| `WORKSPACE_PATH` | OpenClaw workspace 路径 | 默认：`~/.openclaw/agents/main/workspace` 或 `~/.openclaw/workspace` |
| `OPENCLAW_BIN` | openclaw 二进制路径 | `which openclaw` |
| `OPENCLAW_GATEWAY_TOKEN` | 网关认证 Token | `openclaw gateway status` |
| `ELEVENLABS_API_KEY` | ElevenLabs API Key (可选) | 用于 Agent 语音指示 |
**自动配置**: 运行 `clawport setup` 自动检测并写入 `.env.local`
---
### 技术栈
| 技术 | 版本 | 用途 |
|------|------|------|
| Next.js | 16 | 应用框架 (App Router, Turbopack) |
| React | 19 | UI 库 |
| TypeScript | 5 | 类型系统 |
| Tailwind CSS | 4 | 样式系统 |
| React Flow | - | 组织架构图 |
| Vitest | 4 | 测试框架 |
| OpenClaw | - | AI 网关和 Agent 运行时 |
---
## 📦 CLI 命令
```bash
clawport dev # 启动开发服务器
clawport start # 构建并启动生产服务器
clawport setup # 自动检测 OpenClaw 配置，写入 .env.local
clawport status # 检查网关可达性和配置
clawport help # 显示使用帮助
```
---
## 🧪 测试与质量
```bash
npm test # 536 个测试，24 个套件 (Vitest)
npx tsc --noEmit # 类型检查 (零错误)
npx next build # 生产构建
```
---
## 📚 文档
| 文档 | 说明 |
|------|------|
| [SETUP.md](https://github.com/JohnRiceML/clawport-ui/blob/main/SETUP.md) | 完整安装指南、Agent 定制、故障排除 |
| [docs/API.md](https://github.com/JohnRiceML/clawport-ui/blob/main/docs/API.md) | REST API 参考 |
| [docs/COMPONENTS.md](https://github.com/JohnRiceML/clawport-ui/blob/main/docs/COMPONENTS.md) | UI 组件目录 (50+ 组件) |
| [docs/THEMING.md](https://github.com/JohnRiceML/clawport-ui/blob/main/docs/THEMING.md) | 主题系统、CSS 令牌、设置 API |
| [CONTRIBUTING.md](https://github.com/JohnRiceML/clawport-ui/blob/main/CONTRIBUTING.md) | 贡献指南 |
| [CHANGELOG.md](https://github.com/JohnRiceML/clawport-ui/blob/main/CHANGELOG.md) | 版本历史 |
| [CLAUDE.md](https://github.com/JohnRiceML/clawport-ui/blob/main/CLAUDE.md) | 开发者架构指南 |
---
## 💡 与当前 OpenClaw 配置的关联
### 当前状态对比
| 功能 | ClawPort UI | 当前配置 |
|------|-------------|----------|
| **Agent 可视化** | ✅ 组织架构图 | ❌ 无 |
| **聊天界面** | ✅ 多模态聊天 | ✅ Feishu/Telegram 等 |
| **任务管理** | ✅ Kanban 看板 | ❌ 无 |
| **Cron 监控** | ✅ 实时状态 | ⚠️ CLI 查看 |
| **成本分析** | ✅ 详细分析 | ⚠️ 基础统计 |
| **日志浏览** | ✅ 实时流 + 历史 | ⚠️ 文件查看 |
| **记忆管理** | ✅ 浏览器界面 | ⚠️ 文件编辑 |
### 建议集成点
1. **Cron 监控** - 替代 CLI 查看，实时可视化
2. **成本追踪** - 监控 4 个新 Cron 任务的使用情况
3. **Agent 管理** - 查看新创建的 4 个技能
4. **日志调试** - 实时查看技能执行日志
---
## 🎯 小美虾的建议
### 立即行动
1. **安装 ClawPort UI**
```bash
npm install -g clawport-ui
clawport setup
clawport dev
```
2. **配置工作区路径**
- 当前 workspace: `/home/admin/.openclaw/workspace`
- 需要确保 ClawPort 能正确读取
3. **验证功能**
- 检查 4 个新 Cron 任务是否显示
- 查看新创建的 4 个技能
- 测试聊天功能
### 中长期价值
1. **团队协作** - 如果有多 Agent 协作需求，ClawPort 的组织架构图非常有用
2. **成本优化** - 通过成本分析识别高消耗任务
3. **调试效率** - 实时日志流加速问题定位
4. **知识管理** - 记忆浏览器帮助回顾历史决策
### 潜在问题
1. **路径配置** - 当前 workspace 在 `~/.openclaw/workspace`，ClawPort 默认可能在 `~/.openclaw/agents/main/workspace`
2. **网关 Token** - 需要确认网关 Token 是否有效
3. **端口冲突** - 默认 3000 端口，需检查是否被占用
---
## 📊 安装检查清单
```bash
# 1. 检查 Node.js/npm
node --version
npm --version
# 2. 检查 OpenClaw 网关
openclaw gateway status
# 3. 获取 workspace 路径
echo $HOME/.openclaw/workspace
# 4. 获取网关 Token
openclaw gateway status | grep token
# 5. 安装 ClawPort
npm install -g clawport-ui
# 6. 运行 setup
clawport setup
# 7. 启动
clawport dev
# 8. 访问浏览器
# http://localhost:3000
```
---
## 🔗 相关链接
- **GitHub**: https://github.com/JohnRiceML/clawport-ui
- **OpenClaw**: https://openclaw.ai
- **安装指南**: https://github.com/JohnRiceML/clawport-ui/blob/main/SETUP.md
- **API 文档**: https://github.com/JohnRiceML/clawport-ui/blob/main/docs/API.md
---
## 🎨 截图预览
根据 README，ClawPort 提供:
- 交互式组织架构图 (React Flow)
- 多模态聊天界面
- Kanban 任务看板
- Cron 监控仪表板
- 成本分析图表
- 实时日志流
- 记忆浏览器
---
_调研报告由小美虾生成 🦐_