企业官网建设流程全解析

Claude-Code-Agent-Monitor 是一款面向 Claude Code 与 Codex 的实时会话监控仪表盘，它的 API 层提供了两类能力：REST API（基于 HTTP/JSON 的查询与写入）和WebSocket 实时事件流，并附带完整的 OpenAPI 文档，方便开发者快速集成会话监控数据。

30 秒上手：先看交互式 API 文档

在写任何集成代码之前，建议先浏览内置的交互式文档页面。仪表盘启动后（默认端口4820），以下地址均可直接访问：

Swagger UI 中按 Health、Metrics、Sessions、Agents 等分组列出了全部端点，每个端点都可以展开查看请求参数和响应结构：

ReDoc 版本则把左侧导航、中间说明和右侧响应示例并排展示，更适合边查边复制：

静态机器可读规范见 openapi.yaml，人工可读的完整 API 参考文档在 docs/API.md，文档的挂载与渲染逻辑位于 server/index.js 和 server/lib/redoc.js。

REST 端点速览：六大核心命名空间

所有端点都挂在http://localhost:4820/api/*下，返回统一的 JSON 结构。最常用的六组端点如下：

1. Sessions：会话生命周期

会话列表页就是GET /api/sessions的可视化呈现，状态、耗时、Agent 数与费用字段一一对应：

一个常用查询示例（只看最近 10 条进行中的会话）：

curl "http://localhost:4820/api/sessions?limit=10&status=active"

2. Agents / Tools：Agent 与工具执行

• GET /api/agents/:id—— 单个 Agent 详情（状态、token、成本）
• GET /api/agents/:id/tools—— 该 Agent 的工具执行记录（耗时、成功与否、错误信息）
• GET /api/tools—— 全局工具执行流水，可按tool_name、success过滤

3. Pricing：自定义模型计价

• GET /api/pricing—— 查看全部计价规则
• PUT /api/pricing—— 按model_pattern新增或更新规则（美元 / 百万 token）
• DELETE /api/pricing/:pattern—— 删除自定义规则（默认规则不可删）
• 另有/api/pricing/cursor与/api/pricing/gpt两张独立的费率表

4. Metrics：Prometheus 抓取端点

GET /api/metrics以 Prometheus 文本格式暴露ccam_sessions、ccam_agents、ccam_events_total、ccam_tokens_total等指标，让这台监控仪表盘自己也能被 Prometheus/Grafana 抓取。配套的监控栈位于 monitoring/，文档示例见 docs/API.md。

5. Remote Sources：多机历史聚合

/api/remote-sources/*支持通过 SSH 从多台远程机器拉取 Claude Code / Codex 历史，一个面板统一管理多个项目的会话，每条导入的会话都会打上来源 id，可用sources参数过滤。

6. Settings / Run / Webhooks：运维与自动化

• /api/settings/*—— 导出/导入备份、清理数据、管理转录快照、安装 hooks
• /api/run/*—— 直接从面板拉起 Claude Code 或 Codex 子进程并实时接收输出
• /api/webhooks/*—— 告警投递目标（Slack、Discord 等）与投递审计日志

WebSocket 事件流：实时监控的核心

REST 负责"拉数据"，WebSocket 负责"推变化"。连接方式非常简单：

const ws = new WebSocket('ws://localhost:4820/ws'); ws.onmessage = (event) => { const { type, data, timestamp } = JSON.parse(event.data); };

服务端每 30 秒发送一次心跳 ping 来清理死连接（实现见 server/websocket.js）。广播的核心事件类型：

面板的 Live 面板会实时统计事件吞吐、最近事件类型分布，正是对这条 WebSocket 流的直接消费：

认证与安全边界

仪表盘是local-first设计，默认只绑定127.0.0.1，跨域请求被 CORS 与 Host 头白名单拦截（防 DNS-rebinding）。如需局域网暴露：

• 设置DASHBOARD_HOST为更宽的绑定地址，并用DASHBOARD_ALLOWED_HOSTS声明客户端访问的域名
• 强烈建议同时设置DASHBOARD_TOKEN，之后所有/api/*请求与 WebSocket 都需携带令牌，支持三种方式：
  • Authorization: Bearer <token>请求头（推荐）
  • x-dashboard-token: <token>请求头
  • ?token=<token>查询参数

/api/health、/api/openapi.json、/api/docs等只读端点始终免认证；未通过校验的请求返回401及错误码EUNAUTHORIZED。另有独立的REMOTE_PUSH_TOKEN保护面向公网的批量推送端点POST /api/hooks/ingest-batch。

错误处理与分页约定

所有错误响应遵循统一结构：

{ "error": "Session not found", "code": "NOT_FOUND", "details": { "session_id": "sess_invalid" } }

列表类端点统一使用limit+offset分页，响应中附带total、limit、offset、has_more元数据，翻页只需递增 offset。

总结与进一步阅读

Claude-Code-Agent-Monitor 的 API 覆盖了从会话、Agent、工具执行到计价、远程聚合、实时推送的完整链路，配合内置的 Swagger/ReDoc 文档，几乎不需要翻源码就能完成集成。建议按以下路径深入学习：

• 完整端点与字段说明：docs/API.md
• OpenAPI 机器可读规范：openapi.yaml
• WebSocket 广播实现：server/websocket.js
• 路由与端点分组实现：server/routes/
• MCP 工具集成方式：docs/MCP.md

把 REST 查询与 WebSocket 事件流结合起来，你就能构建出属于自己的 Agent 成本看板、告警机器人或 CI 集成脚本——这正是这套 API 设计的初衷。