# 多代理可观测性方案：Claude Code与Codex的统一监控平台

> multi-agents-claude-codex项目提供了一个本地部署的实时可观测性仪表板，统一追踪Claude Code和OpenAI Codex的代理事件，帮助开发者监控多代理工作流的完整生命周期。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-04-11T00:40:35.000Z
- 最近活动: 2026-04-11T00:49:11.131Z
- 热度: 161.9
- 关键词: AI代理, 可观测性, Claude Code, Codex, 监控, Hook, Vue, Bun, SQLite
- 页面链接: https://www.zingnex.cn/forum/thread/claude-codecodex
- Canonical: https://www.zingnex.cn/forum/thread/claude-codecodex
- Markdown 来源: ingested_event

---

## 多代理开发的观测困境

当AI代理工作从单一会话扩展到多代理协作时，可观测性成为关键挑战。开发者需要回答的问题变得复杂：

- 哪个代理正在执行什么任务？
- 工具调用的输入输出是什么？
- 会话之间的调用关系如何？
- 模型选择和性能表现如何？
- 失败发生在哪个环节？

传统的日志记录方式难以应对这种复杂性。代理事件分散在不同进程的输出中，缺乏统一的时间线和关联分析。当出现问题时，开发者往往需要在多个终端窗口和日志文件之间来回切换，效率低下且容易遗漏关键信息。

## 项目概述：统一的可观测性层

multi-agents-claude-codex项目构建了一个本地运行的可观测性平台，通过Hook机制捕获Claude Code和Codex的运行时事件，提供统一的监控、分析和审计能力。

该项目的核心创新在于同时支持两个主流AI编程代理——Anthropic的Claude Code和OpenAI的Codex，并通过标准化的数据模型实现跨平台的事件关联分析。

## 架构设计：从Hook到仪表板

### 数据采集层

项目通过两种机制捕获代理事件：

**Claude Code Hooks**：利用Claude Code的settings.json配置，在关键生命周期点（SessionStart、UserPromptSubmit、PreToolUse、PostToolUse等）触发Python脚本，将事件数据发送到本地服务器。

**Codex Hooks**：通过.codex/hooks.json配置，同样捕获Codex会话的事件。特别值得注意的是，项目设计让Codex保持OAuth凭证的所有权，Hook脚本仅接收事件JSON，不接触敏感认证信息。

### 标准化处理层

不同代理平台的事件格式各异。项目通过`normalize.ts`模块将Claude Code和Codex的原始负载转换为统一的标准化事件模型，同时保留原始数据用于深度分析。

标准化事件包含以下关键字段：
- 运行时标识（claude-code / codex）
- 事件类别（session、turn、tool、agent等）
- 状态信息（started、completed、failed、blocked）
- 模型名称和工具信息
- 持续时间、工作目录、会话关联

### 存储与流式传输

事件数据存储在本地SQLite数据库中，同时通过WebSocket实时推送到前端仪表板。这种设计既保证了数据的持久化，又支持实时监控场景。

### 可视化仪表板

基于Vue 3构建的Web界面提供：
- 时间线视图：按时间顺序展示所有代理事件
- 过滤器：按源应用、会话、事件类型、模型、工具筛选
- 聊天转录：查看完整的对话历史
- 图表分析：统计视图展示代理活动模式

## 关键特性详解

### 跨平台统一监控

这是项目最显著的特点。开发者可以在同一个仪表板中同时观察Claude Code和Codex的活动，比较两者的行为模式，甚至分析跨平台的协作场景。

标准化事件模型让这种统一成为可能。无论底层代理如何不同，上层分析工具都使用一致的接口。

### 隐私优先的Codex集成

与Codex的集成特别注重隐私保护：
- 不读取~/.codex/auth.json中的凭证
- 不复制或存储OAuth令牌
- 不需要OpenAI API密钥
- 仅接收Hook传递的事件JSON

这种设计让团队可以在不暴露敏感认证信息的情况下获得Codex的可观测性。

### 丰富的Hook覆盖

项目为Claude Code提供了全面的Hook覆盖：

- **生命周期**：session_start、session_end、user_prompt_submit、stop
- **工具使用**：pre_tool_use、post_tool_use、post_tool_use_failure
- **多代理**：subagent_start、subagent_stop
- **交互与权限**：permission_request、notification

这种细粒度的覆盖确保了代理活动的完整可见性。

### 本地优先的部署

整个系统基于Bun运行时、SQLite数据库和Vue前端，完全本地运行，无需云服务或外部依赖。这种架构选择带来了几个优势：

- **数据主权**：敏感代码和对话历史不会离开本地机器
- **低延迟**：本地WebSocket通信确保实时监控的响应速度
- **零成本**：无需支付云服务费用
- **可定制**：开源代码允许根据团队需求定制

## 典型使用场景

### 调试复杂的多代理工作流

当多个代理协同完成一个任务时，通过时间线视图可以清晰地看到会话启动顺序、工具调用链和代理间的消息传递。当某个步骤失败时，可以快速定位问题所在。

### 性能分析与优化

通过收集的持续时间数据，团队可以分析：
- 哪些工具调用耗时最长
- 不同模型的响应时间对比
- 代理会话的整体效率

这些洞察有助于优化工作流设计和模型选择。

### 安全审计与合规

完整的操作日志为安全审计提供了基础。团队可以回顾：
- 哪些敏感操作被执行
- 权限请求的处理情况
- 失败和异常事件的分布

### 团队知识共享

仪表板的历史记录功能让团队成员可以回顾彼此的代理会话，学习最佳实践，避免重复踩坑。

## 技术栈与部署

项目采用现代Web技术栈：

- **后端**：Bun + TypeScript + SQLite
- **前端**：Vue 3 + TypeScript
- **通信**：HTTP API + WebSocket
- **构建工具**：Vite（前端）、Bun（后端）
- **任务运行器**：just（替代Make）

部署流程简单明了：

```bash
# 安装依赖
just install

# 启动服务
just start

# 打开仪表板
just open
```

默认端口配置：
- 服务器：http://localhost:4000
- 事件API：http://localhost:4000/events
- WebSocket：ws://localhost:4000/stream
- 客户端：http://localhost:5173

## 扩展性与未来方向

项目的标准化事件模型为扩展奠定了基础。未来可以轻松添加对其他AI代理的支持，如：

- GitHub Copilot Chat
- Cursor Composer
- Continue.dev
- 自定义代理实现

此外，收集的数据还可以用于：
- 机器学习：训练代理行为预测模型
- 成本分析：追踪API调用成本
- 安全检测：识别异常代理行为模式

## 对AI工程实践的启示

multi-agents-claude-codex项目反映了AI工程实践的一个重要趋势：从"黑盒代理"向"可观测代理"的转变。

早期的AI代理工具往往将内部 workings 隐藏起来，用户只能通过输出判断其行为。随着代理承担越来越复杂的任务，这种不透明性成为生产部署的障碍。

可观测性不仅是为了调试，更是为了建立对AI系统的信任。当团队能够清晰地看到代理在做什么、为什么这么做、结果如何时，才能放心地将关键任务委托给它们。

## 总结

multi-agents-claude-codex为AI代理开发团队提供了一个实用的可观测性解决方案。通过Hook机制捕获事件、标准化数据模型、本地部署架构，它平衡了功能完整性和隐私安全性。

对于正在采用Claude Code或Codex的团队，这个项目值得作为基础设施的一部分进行评估。它不仅解决了当下的观测需求，更为未来多代理协作的复杂性提供了可扩展的基础。