企业官网建设流程全解析

Claude-Code-Agent-Monitor是一款实时 AI 代理监控面板（Agent Dashboard），专为 Claude Code 与 Codex 打造。它基于 Node.js、Express、React、SQLite 和 WebSocket 构建，能够追踪会话、Agent 活动、工具调用、子代理（Subagent）编排，并提供实时数据分析、Kanban 状态看板、状态通知和漂亮的 Web 界面。本文带你用 3 分钟完成安装，并详解最关键的 Claude Code Hooks 配置。

一、它能帮你看到什么？

如果你每天都在用 Claude Code，一定有过这样的疑问：Agent 现在在干什么？卡在哪里了？这个会话花了多少钱？

Claude-Code-Agent-Monitor 一次性回答这些问题：

• Dashboard 总览：会话数、Agent 活动、成本、Token 消耗一屏可见
• Kanban 看板：按 Working / Waiting / Completed / Error 分列，实时掌握每个 Agent 状态
• 会话列表：所有历史会话，含成本、模型、Agent 数量、时长
• 活动流（Activity Feed）：工具调用事件实时滚动
• Analytics 分析：按模型统计 Token、工具使用频率、活跃热力图
• 成本追踪：基于模型定价规则估算每个会话的花费

二、环境要求（10秒确认）

三、3分钟安装步骤（最快配置方法）

第 1 步：克隆仓库

git clone https://gitcode.com/gh_mirrors/cl/Claude-Code-Agent-Monitor cd Claude-Code-Agent-Monitor

第 2 步：安装依赖

npm run setup

这一条命令会安装服务端和客户端依赖、构建本地 MCP 包，并把ccamCLI 链接到全局路径。安装过程中若看到better-sqlite3的编译报错属于正常现象（它是可选的原生加速模块，项目会自动回退到 Node 22 内置的node:sqlite），不用理会。

第 3 步：启动面板

npm run dev

然后打开浏览器访问http://localhost:5173（开发模式）即可。面板启动后，会自动把 Claude Code 的 Hooks 配置写入~/.claude/settings.json——这是新手最容易忽略、也最关键的一步，下一节详细讲。

第 4 步：开一个 Claude Code 会话

# 在任意项目目录的另一个终端执行 claude

看到 Dashboard 上出现会话卡片、Kanban 上出现Main Agent、活动流开始滚动，就说明装好了 🎉

💡 生产模式（单进程、构建后客户端）：npm run build && npm start，访问http://localhost:4820。

四、Claude Code Hooks 配置详解（核心）

4.1 Hooks 是什么？

Claude Code 自带一套Hooks（钩子）系统：在 Agent 生命周期的关键时刻（开始会话、调用工具前后、回合结束……）自动执行你指定的命令。

Claude-Code-Agent-Monitor 的原理就是"寄生"在这套钩子上：

Claude Code 触发钩子 → hook-handler.js 读取 JSON 事件 → POST 到本地面板（默认端口 4820）→ 写入 SQLite → WebSocket 广播 → 界面实时刷新

整个过程非阻塞：钩子失败或面板没启动都不会影响 Claude Code 正常运行，单次处理约 70ms。

4.2 一键安装 Hooks

npm run install-hooks

安装器是交互式的：方向键 + 空格 + 回车，可勾选Claude Code、Codex (beta)或两者（默认已选 Claude Code）。它只会写入本面板自己的钩子条目，你原有的其他钩子会被完整保留。之后也可以在面板Settings → Hook Configuration → Install hooks里重新安装。

4.3 它往~/.claude/settings.json写了什么？

安装脚本 scripts/install-hooks.js 会为以下8 种事件各注册一条钩子，指向 scripts/hook-handler.js：

其中PreToolUse、PostToolUse等 5 类带"matcher": "*"（匹配所有工具），SessionStart等 3 类不支持 matcher。服务端的事件处理入口在 server/routes/hooks.js，完整文档见 docs/HOOKS.md。

4.4 验证钩子是否生效

# 面板健康检查（在运行 Claude Code 的同一台机器上执行） curl http://127.0.0.1:4820/api/health

再开一个真实的 Claude Code 会话，30 秒内面板出现数据即代表配置成功。若完全没有数据，先检查~/.claude/settings.json中的hooks字段是否存在、路径是否指向真实的hook-handler.js（注意：Docker 里运行时必须在宿主机执行npm run install-hooks，容器内安装会写入无效路径）。

五、装好后立刻值得一看的页面

① 活动流（Activity Feed）——每次工具调用实时滚动，支持暂停、过滤、一键跳转到对应会话：

② 会话列表（Sessions）——按状态、名称搜索过滤，含成本与时长：

③ Analytics——Token 用量、工具频率、活跃热力图，帮你找到"最烧钱"的模型：

④ 设置页（Settings）——模型定价规则、钩子安装状态、数据导出/清理都在这里：

六、进阶小贴士（可选）

没有历史数据？先看点演示数据：

npm run seed # 生成 8 个示例会话、23 个 Agent、106 条事件

想导入旧会话？面板启动时会自动导入~/.claude/projects/下的全部历史；来自其他机器的.jsonl / .zip / .tar.gz可在Settings → Import History上传，重复导入不会重复计费。

命令行党：npm run setup之后可用ccamCLI 在任意终端查看状态，例如ccam status、ccam overview、ccam tail，完整手册见 docs/CLI.md。

七、常见问题排查清单

更多细节可参考 INSTALL.md 与 SETUP.md。

小结

回看这 3 分钟：git clone→npm run setup→npm run dev，配合一条npm run install-hooks，你就拥有了一个覆盖会话、Agent、工具调用、Token 与成本的全景监控面板。前端源码在 client/src/pages/，后端在 server/，数据统一落在本地 SQLite（server/db.js），零云服务、零外部 CDN 请求，放心装起来用吧 🚀