> ## Documentation Index
> Fetch the complete documentation index at: https://docs.befailproof.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 控制台

> 监控 Agent 会话、审查工具调用并管理策略

failproofai 控制台是一个本地 Web 应用，用于监控 AI Agent 会话及管理策略。查看 Agent 在后台执行的所有操作。

***

## 启动控制台

```bash theme={null}
failproofai
```

访问地址：`http://localhost:8020`。

控制台直接从文件系统读取本地项目、会话及 failproofai 配置数据。审计提醒和邀请等可选的认证功能，会将相关请求所需的信息（包括电子邮件地址）发送至远程 API。

***

## 页面说明

### 项目

列出本机上所有 Claude Code、OpenAI Codex、GitHub Copilot CLI *(beta)*、Cursor Agent *(beta)*、OpenCode *(beta)*、Pi *(beta)*、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 和 Goose 项目。Claude 项目从 `~/.claude/projects/`（或 `CLAUDE_PROJECTS_PATH` 指定的路径）中发现；Codex 项目通过扫描 `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` 下的所有记录，并按每个会话首条记录中的 `cwd` 字段分组；Copilot CLI 项目通过扫描每个 `~/.copilot/session-state/<sessionId>/workspace.yaml`（可通过 `COPILOT_HOME` 配置）并按其 `cwd` 字段分组；Cursor Agent 项目通过扫描 `~/.cursor/agent-sessions/<sessionId>/`（可通过 `CURSOR_HOME` 配置，同时以 `conversations/` 和 `sessions/` 作为备用路径）下各会话的元数据，从 `meta.json` / `session.json` / `workspace.yaml` 中读取 `cwd` 标量；OpenCode 项目通过 `opencode db --format json` 查询位于 `~/.local/share/opencode/opencode.db` 的 SQLite 数据库（读取 `session` 和 `project` 表，按 `project_id` 分组）；Pi 项目通过扫描 `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl`（可通过 `PI_SESSIONS_DIR` 配置）下各会话的 JSONL 记录，并从每个会话首条记录中提取 `cwd`；Hermes 网关会话直接从位于 `~/.hermes/state.db`（可通过 `HERMES_DB_PATH` 配置）的 SQLite 存储中读取，按 `source`（Slack/Telegram/cli/cron）分组为 `hermes-<source>` 项目（网关会话无 cwd）；OpenClaw 网关会话从 `~/.openclaw/agents/<agentId>/sessions/*.jsonl` 读取，分组为 `openclaw-<agentId>` 项目（同样无 cwd）；Factory Droid 项目从 `~/.factory/sessions/<encoded-cwd>/*.jsonl` 的 JSONL 记录中发现，按 cwd 分组；Devin 项目来自位于 `~/.local/share/devin/cli/sessions.db` 的 SQLite 数据库（按每个会话的 `working_directory` 分组）；Antigravity 项目来自 `~/.gemini/antigravity-cli/brain/<conversationId>/…/transcript_full.jsonl` 的 JSONL 记录，按 cwd 分组；Goose 项目来自位于 `~/.local/share/goose/sessions/sessions.db` 的 SQLite 数据库（按每个会话的 `working_dir` 分组）。被多个 CLI 使用的项目会以单行显示，并标注所有匹配的徽标。使用表格上方的 **CLI** 下拉菜单可按特定 Agent CLI 筛选；所选项会以 `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose` 的形式保留在 URL 中。

每个项目显示：

* 项目名称（从文件夹路径提取）
* CLI 徽标 — `Claude Code`（橙色）、`OpenAI Codex`（紫色）、`GitHub Copilot`（蓝色）、`Cursor Agent`（翠绿色）、`OpenCode`（琥珀色）、`Pi`（粉色）和/或 `Hermes`（靛蓝色）
* 最近会话活动日期

点击项目可查看其会话列表。

### 会话

列出项目内的所有会话。每个会话显示：

* 会话 ID
* 开始和结束时间戳
* 工具调用次数
* Hook 活动次数（已触发的策略数）

使用日期范围筛选器和会话 ID 搜索来缩小列表范围。会话支持分页显示。

点击会话可打开会话查看器。

### 会话查看器

会话查看器回答了自主 Agent 的核心问题：Agent 做了什么，是否保持在正轨上？标题旁的 CLI 徽标表明该会话是 Claude Code、OpenAI Codex、GitHub Copilot CLI、Cursor Agent、OpenCode、Pi、Hermes、OpenClaw、Factory Droid、Devin、Antigravity 还是 Goose 的记录。它以时间线形式展示会话中发生的一切：

* **消息** - Claude 的文本回复和用户提示
* **工具调用** - Claude 调用的每个工具及其输入输出
* **策略活动** - 每次工具调用触发了哪些策略，以及策略返回的决策

顶部的统计栏显示会话时长、工具调用总数，以及 Hook 决策摘要（allow / deny / instruct 计数）。

点击 **下载日志** 按钮可导出会话。对于 Claude Code、Codex、Copilot、Cursor 和 Pi 会话，您将获得磁盘上原始的 JSONL 记录文件（字节完全一致）；对于 OpenCode（会话存储在 SQLite 而非磁盘文件中），您将获得一个镜像底层 `session` / `messages` / `parts` 表结构的 JSON 文档。

### 审计

一份带有个性化特征的报告，展示 Agent 在过去会话中的实际行为。运行与 `failproofai audit` CLI 相同的扫描逻辑，并以单屏可分享海报 + 四个折叠区块的形式呈现：

1. **海报** — 填满第一屏视口。独立的 PNG 截图区域，包含 failproof\_ai 字标 + 审计标签 · 原型索引（`№ NN of 08`）+ 审计日期 · 数字评分（0–100）+ 百分位排名标签（`top 15%`）· 原型名称（`the optimist`、`the cowboy`、`the explorer`、`the goldfish`、`the paranoid architect`、`the precision builder`、`the hammer`、`the ghost` 之一）+ 3 个关键词条 · `// only N% of agents are this archetype` 稀有度行 · 8×8 像素印记图块 · `audit yours → failproof.ai` 页脚。截图框外侧有三个分享按钮：`post your archetype`（X 分享）、`share on linkedin`、`download poster`。截图通过 `html-to-image` 生成，PNG 与屏幕渲染像素级一致（虚线边框、SVG 蒙版、渐变、字体度量均完整保留）。
2. **优势** — 以 ✓ 行的形式平静列出 Agent 已表现良好的行为，源自实时审计数据（工具调用通过率高、未直接推送至主分支、零凭证泄露、零重试风暴）——仅在相关策略在审计窗口内记录清白时才会显示。
3. **不足** — 按严重程度排列的滑点列表：`时间 · 滑点内容 + 可捕获它的策略 · 严重程度标签 · 出现次数`，其中出现次数标注为 `new`（仅一次）、`N× seen`（2–9 次）或 `recurring`（10 次及以上）。
4. **改进建议** — 平静列表，每行对应一项推荐策略：策略名称以白色显示，一行描述，右侧为安装命令和复制按钮。区块标题显示 `enable all N → projected <score> · <tier>`（应用所有修复后可达到的评分），其 `[install all]` 按钮可复制所有推荐策略的组合安装命令 `failproofai policy add a b c …`。
5. **下次更好** — 两张并排卡片。左侧：设置提醒（`3d` / `7d` / `14d` / `30d` 周期选择器；通过 `/api/auth/reminder` 在认证后持久化）。右侧：解锁 failproof 特权 — `invite a friend` 打开一个对话框，输入以逗号/空格/换行符分隔的好友邮箱列表（每次最多 10 个），通过 POST 发送至 `/api/audit/invite`，再转发至 api-server 的 `POST /v0/invite`。api-server 从 `invite@failproof.ai` 向每位收件人发送邮件，抄送发件人并设置 `Reply-To`，收件人可看到邀请人信息，发件人也会在收件箱收到副本。匿名用户会先通过 `AuthDialog` 流程，确认发件人邮箱后再发送邀请。权益/特权功能将在后续版本中推出。

由 `failproofai audit` 运行时驱动——扫描引擎、支持的标志及每条记录缓存规则，详见 [审计 CLI](/zh/cli/audit)。控制台将最新结果缓存至 `~/.failproofai/audit-dashboard.json`（权限 `0600`，单槽位，新运行覆盖旧结果），以实现即时回访；**每条记录缓存和整体结果缓存在读取时超过 7 天即失效**，控制台不会静默返回一周前的旧结果——超过 TTL 后，`/audit` 将显示空状态并提示重新运行。点击报告底部的 `[ re-audit now ]` 会向 `/api/audit/run` 发送 `noCache: true` 的 POST 请求——重新审计会绕过每条记录的缓存，从头重新扫描所有记录，而不是静默返回缓存结果——控制台以 1Hz 轮询 `/api/audit/status` 直至运行完成；运行期间，视口顶部会固定显示一条带有计时器的粉色进度条，运行成功后结果就地更新（无需整页刷新；重新审计失败则保留之前的报告）。失败时进度条变红，并根据 `RerunError.kind`（`timeout` / `network` / `post_failed`）显示对应的错误提示。无缓存或缓存过期的空状态，与缓存存在但扫描未发现任何记录的零会话状态，会分别单独展示。

### 策略

一个包含两个标签页的页面，用于管理策略和查看活动记录。

<Tabs>
  <Tab title="策略标签页">
    * 在单一面板中多选 failproofai 保护的 Agent CLI — Claude Code、OpenAI Codex、GitHub Copilot、Cursor Agent、OpenCode、Pi 和 Hermes 各有一行，显示安装状态（`Active` / `Detected` / `Inactive`）、用户级配置路径以及品牌色调。勾选或取消勾选所需 CLI，点击 `Apply changes` 即可一步完成安装/卸载差异。PATH 中检测到二进制文件的 CLI 会预先勾选。
    * 单击即可启用或禁用单项策略（写入 `~/.failproofai/policies-config.json`——所有已安装的 CLI 共享此配置）
    * 展开策略可配置其参数（适用于支持 `policyParams` 的策略）
    * 设置自定义策略文件路径
  </Tab>

  <Tab title="活动标签页">
    * 所有会话中已触发的每个 Hook 事件的完整分页历史记录
    * 按决策、事件类型、CLI（Claude Code / OpenAI Codex / GitHub Copilot *(beta)* / Cursor Agent *(beta)* / OpenCode *(beta)* / Pi *(beta)* / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose）、策略名称或会话 ID 筛选
    * 每行显示：时间戳、策略名称、决策、CLI 徽标（橙色 = Claude Code、紫色 = OpenAI Codex、蓝色 = GitHub Copilot、翠绿色 = Cursor Agent、琥珀色 = OpenCode、粉色 = Pi、靛蓝色 = Hermes、青色 = OpenClaw、玫瑰色 = Factory Droid、紫罗兰色 = Devin、青蓝色 = Antigravity、黄绿色 = Goose）、工具名称、会话 ID，以及 deny/instruct 决策的原因
    * 点击会话 ID 可打开对应记录——查看器自动检测触发 Hook 的 CLI（Claude `~/.claude/projects/…`、Codex `~/.codex/sessions/…`、Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`、Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`、OpenCode `~/.local/share/opencode/opencode.db`、Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`、Hermes `~/.hermes/state.db`、OpenClaw `~/.openclaw/agents/<id>/sessions/*.jsonl`、Factory Droid `~/.factory/sessions/<encoded-cwd>/<id>.jsonl`、Devin `~/.local/share/devin/cli/sessions.db`、Antigravity `~/.gemini/antigravity-cli/brain/<id>/…/transcript_full.jsonl`、Goose `~/.local/share/goose/sessions/sessions.db`），并在标题中渲染对应的 CLI 徽标
  </Tab>
</Tabs>

***

## 自动刷新

控制台顶部导航栏提供自动刷新开关。启用后，当前页面会定期刷新，实时显示新会话和策略活动。这对于监控长时间运行的自主 Agent 会话至关重要。

***

## 禁用页面

如果只需要控制台的部分功能，可将 `FAILPROOFAI_DISABLE_PAGES` 设置为以逗号分隔的页面名称列表：

```bash theme={null}
FAILPROOFAI_DISABLE_PAGES=policies failproofai
```

有效值：`policies`、`projects`、`audit`。

***

## 配置项目路径

默认情况下，控制台从标准 Claude Code 项目目录读取数据。如需自定义路径，可通过以下方式覆盖：

```bash theme={null}
CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
```

***

## 从非 localhost 主机访问

在**开发模式**（`npm run dev`）下运行控制台，并从非 `localhost` 的主机名访问时——例如自定义域名、远程 IP 或隧道 URL——可能会看到如下警告：

```text theme={null}
⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
```

这是 Next.js 阻止跨域访问其 HMR（热模块重载）WebSocket 的提示，该功能仅在开发模式下存在。如需允许您的主机，请使用 `--allowed-origins` 标志：

```bash theme={null}
npm run dev -- --allowed-origins dashboard.example.com
```

如需允许多个主机或 IP，传入以逗号分隔的列表：

```bash theme={null}
npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
```

也可以改为设置 `FAILPROOFAI_ALLOWED_DEV_ORIGINS` 环境变量：

```bash theme={null}
FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
```

<Note>
  此设置仅适用于开发模式。在运行 `failproofai`（生产模式）时，不存在 HMR WebSocket，也不存在跨域开发资源问题。
</Note>