内容
# 欧姆诺德克斯
[](https://github.com/omnodex/omnodex/actions/workflows/ci.yml)
**AI 代理执行的 安全性和可观察性。** 欧姆诺德克斯捕获了 AI 代理执行的每个工具调用、凭证使用、文件访问和第三方连接 - 并将其公开以供人工审查。
核心流程：**拦截 -> 跟踪 -> 分析 -> 报告。** 对代理会话的令牌开销为零。
完整文档：[docs.omnodex.com](https://docs.omnodex.com/)
---
## 集成
欧姆诺德克斯支持多种拦截表面。请选择与您的代理运行方式相匹配的表面。
---
### 克劳德代码
#### 命令行 / 终端
主要集成。欧姆诺德克斯钩入克劳德代码的原生钩子系统 - 钩子在代理的上下文窗口之外异步触发，不增加令牌开销。
**先决条件**
- Node.js 24 或更新版本
- 已安装并认证克劳德代码
**安装**
```bash
npm install -g omnodex # 或：npx omnodex
```
**为项目启用钩子**
```bash
cd /your/project
omnodex install claude-code
```
这将欧姆诺德克斯钩子条目写入 `.claude/settings.local.json`。克劳德代码在下一次会话启动时自动拾取它们 - 无需重启。
选项：
```
omnodex install claude-code [project] # 默认当前工作目录
omnodex install claude-code --debug #详细shim日志输出到stderr
omnodex install claude-code --project-settings #写入settings.json
```
要删除钩子：
```bash
omnodex uninstall claude-code --confirm
```
**查看仪表盘**
```bash
omnodex dashboard
# 打开 http://localhost:7890
```
仪表盘显示连接图、凭证账本、风险事件和带有点击详细信息的完整事件时间线。它通过SSE实时更新 - 风险被检测并推送到浏览器，因为每个工具调用到达。
**多源聚合：** 如果您同时运行多个代理表面（例如，Windows上的Cowork + WSL中的克劳德代码），仪表盘可以同时跟踪所有这些表面。 在 `~/.omnodex/config.json` 中配置其他根目录：
```json
{
"dashboard": {
"roots": ["\\\\wsl$\\Ubuntu\\home\\you\\.omnodex"]
}
}
```
或作为命令行标志传递：`omnodex dashboard --roots /path/to/.omnodex`。 默认根目录（`~/.omnodex`）始终包含。 来自所有根目录的事件合并到单个时间线中，可按来源筛选。
---
#### IDE 扩展（VS Code，Cursor，JetBrains）
克劳德代码的IDE扩展使用相同的 `.claude/settings.local.json` 钩子配置作为命令行。 在项目目录中运行 `omnodex install claude-code`，钩子将自动在基于IDE的克劳德代码会话中触发。
---
#### claude.ai 网页
> **暂不可用。** claude.ai 网页界面不支持本地MCP服务器或钩子。 欧姆诺德克斯将通过托管的MCP代理支持claude.ai网页会话。
---
#### 克劳德桌面 - claude.ai 聊天应用
克劳德桌面聊天应用通过其配置支持MCP服务器。 添加 `omnodex-mcp-proxy` 作为MCP服务器，并将现有的MCP服务器路由通过它以捕获所有工具调用。
```json
{
"mcpServers": {
"omnodex": {
"command": "omnodex-mcp-proxy",
"args": []
}
}
}
```
在欧姆诺德克斯代理配置中配置上游服务器（参见 `omnodex mcp-proxy install`）。
---
#### Cowork
欧姆诺德克斯通过MCP代理插件与Cowork集成。 代理位于Cowork和上游MCP服务器之间，捕获每个工具调用到欧姆诺德克斯事件日志。
安装欧姆诺德克斯插件并在插件的 `mcp.json` 中添加 `omnodex-mcp-proxy` 作为MCP服务器命令。 所有Cowork MCP流量都通过代理透明地流动。
> **注意：** 基于钩子的拦截在Cowork中不可用 - 插件贡献的钩子目前被忽略上游（[#27398](https://github.com/anthropics/claude-code/issues/27398)，[#40495](https://github.com/anthropics/claude-code/issues/40495)）。 MCP代理方法为所有MCP工具调用提供等效覆盖。
---
### OpenAI Codex
#### 命令行 / 终端
欧姆诺德克斯与Codex钩子系统集成，使用与克劳德代码集成相同的架构：一个轻量级shim子进程接收钩子有效载荷，通过stdin将其映射到欧姆诺德克斯跟踪事件，并将它们追加到事件日志中，而不影响代理的执行路径。
**先决条件**
- Node.js 24 或更新版本
- Codex CLI 已安装
**在您的Codex配置中启用钩子**
Codex钩子需要一个选择加入的功能标志。 将以下内容添加到 `~/.codex/config.toml` （或项目本地的 `.codex/config.toml`）：
```toml
[features]
codex_hooks = true
```
**安装**
```bash
npm install -g omnodex # 或：npx omnodex
```
**为项目启用钩子**
```bash
cd /your/project
omnodex install codex
```
这将欧姆诺德克斯钩子条目写入 `.codex/hooks.json`。 Codex 自动拾取它们。
选项：
```
omnodex install codex [project] # 默认当前工作目录
omnodex install codex --debug #详细shim日志输出到stderr
```
要删除钩子：
```bash
omnodex uninstall codex --confirm
```
**查看仪表盘**
与克劳德代码相同 - 运行 `omnodex dashboard` 并打开 `http://localhost:7890`。
**已知限制（Codex钩子仍在开发中）**
Codex钩子当前仅适用于Bash工具调用。 以下内容 **不** 通过钩子拦截：
- 文件写入（`apply_patch`）
- MCP工具调用
- Web搜索
- `unified_exec` shell调用（仅部分拦截）
这些是Codex钩子覆盖范围的上游空白（[#20204](https://github.com/openai/codex/issues/20204)）。 欧姆诺德克斯架构已准备就绪 - 当Codex发布时，覆盖范围将自动扩展。
---
#### IDE 扩展（VS Code，Cursor）
Codex IDE扩展使用与CLI相同的 `.codex/` 配置目录。 在您的项目中运行 `omnodex install codex`，IDE会话中的钩子将触发。
---
#### Codex 桌面应用
Codex桌面应用在后台运行Codex CLI，并共享相同的 `.codex/hooks.json` 配置。 `omnodex install codex` 适用于桌面会话。
为了实现Codex钩子当前支持范围之外的完整工具覆盖（文件写入，MCP调用），请在基于钩子的方法旁边运行欧姆诺德克斯MCP代理。 参见下面的 [MCP代理](#mcp-proxy) 部分。
---
#### Codex 网页
> **暂不可用。** Codex网页会话将通过托管的欧姆诺德克斯MCP代理获得支持。
---
### Google Antigravity
#### 命令行，桌面应用，IDE扩展
欧姆诺德克斯通过共享代理程序与Google Antigravity的钩子系统集成。 单个 `omnodex install antigravity` 命令涵盖所有三个表面（CLI `agy`，桌面应用和IDE扩展），因为它们共享相同的 `.agents/hooks.json` 配置。
**先决条件**
- Node.js 24 或更新版本
- Google Antigravity 已安装（CLI，桌面或IDE扩展）
**安装**
```bash
npm install -g omnodex # 或：npx omnodex
```
**为项目启用钩子**
```bash
cd /your/project
omnodex install antigravity
```
这将欧姆诺德克斯钩子条目写入 `.agents/hooks.json`。 Antigravity 的所有表面都自动拾取它们。
选项：
```
omnodex install antigravity [project] # 默认当前工作目录
omnodex install antigravity --debug #详细shim日志输出到stderr
```
要删除钩子：
```bash
omnodex uninstall antigravity --confirm
```
**查看仪表盘**
与其他集成相同 - 运行 `omnodex dashboard` 并打开 `http://localhost:7890`。
---
### MCP 代理
对于不支持钩子API的代理和平台，欧姆诺德克斯提供了一个通用的MCP代理。 将代理的MCP流量路由到欧姆诺德克斯代理，欧姆诺德克斯捕获工具调用、数据流和凭证使用情况，适用于任何MCP兼容的代理 - 无论模型或运行时如何。
```bash
# 生成代理配置文件模板
omnodex mcp-proxy install
# 检查配置
omnodex mcp-proxy status
# 启动代理
omnodex mcp-proxy start
```
代理配置映射上游MCP服务器。 将您的代理指向 `omnodex-mcp-proxy` 而不是其通常的MCP服务器，代理将转发所有流量，同时将每个工具调用记录到欧姆诺德克斯事件日志中。
目标平台：Cowork，克劳德桌面，Codex桌面（完整工具覆盖），claude.ai 网页（需要托管代理），Codex网页（需要托管代理），以及连接到MCP服务器的任何其他代理。
---
## 快速入门（模拟管道）
在不连接到实时代理的情况下探索欧姆诺德克斯：
```bash
npm install
npx tsc -b
# 运行模拟会话通过完整管道
OMNODEX_HOME=/tmp/omnodex-demo node packages/cli/dist/index.js spike
# 在捕获的事件中检测风险
OMNODEX_HOME=/tmp/omnodex-demo node packages/cli/dist/index.js detect
# 启动仪表盘
OMNODEX_HOME=/tmp/omnodex-demo node packages/cli/dist/index.js dashboard
# 打开 http://localhost:7890
```
所有数据都存储在 `OMNODEX_HOME` 下（默认为 `~/.omnodex`）。
---
## CLI 参考
```
omnodex install <target> [project] 为AI代理平台安装钩子
targets: claude-code, codex, antigravity
--debug 详细shim日志输出到stderr
--project-settings (claude-code) 编辑
settings.json 而不是
omnodex uninstall [target] [project] 删除欧姆诺德克斯钩子（需要 --confirm）
omnodex status [project] 显示已安装的钩子
omnodex mcp-proxy <subcommand> 管理MCP代理拦截器
install 生成代理配置文件模板
status 检查当前配置
start 启动代理服务器
omnodex spike [name] 运行模拟会话通过完整管道
omnodex detect [session] 扫描事件日志中的风险（如果省略，则扫描所有会话）
omnodex replay 从事件日志重建SQLite读取模型
omnodex report 打印会话摘要
omnodex dashboard [port] 启动本地仪表盘（默认端口7890）
--roots <path> [path...] 额外的OMNODEX_HOME
根目录到尾部
--no-detect 跳过历史检测过程
omnodex clear 删除所有事件日志数据和读取模型
omnodex license 管理许可证激活和状态
```
---
## 架构
1. **事件日志优先存储。** 真相的来源是 `$OMNODEX_HOME/event-log/sessions/` 下的追加JSONL事件日志。 SQLite是一个派生的读取模型，通过重放日志重建。 仪表盘支持同时跟踪多个根目录，以实现多源聚合。
2. **异步设计。** 拦截器将事件追加到事件日志并退出。 它们永远不会阻塞代理的执行路径。 投影器和分析器异步运行，并允许滞后。
3. **单个 `Interceptor` 接口。** 每个拦截源都实现 `@omnodex/shared` 中的相同合约。 五个实现已完成：`ClaudeCodeInterceptor`、`CodexInterceptor`、`AntigravityInterceptor`、`MCPProxy` 和 `MockInterceptor`。 额外的拦截器无需修改下游即可接入。
4. **零令牌开销。** 基于钩子的架构在代理的上下文窗口之外运行。 没有任何拦截方法会消耗客户的令牌。
---
## 测试
```bash
# 所有软件包
node --test \
packages/event-log/test/*.test.mjs \
packages/projection/test/*.test.mjs \
packages/hooks-provider/test/*.test.mjs \
packages/codex-provider/test/*.test.mjs \
packages/antigravity-provider/test/*.test.mjs \
packages/cli/test/*.test.mjs \
packages/analyzer/test/**/*.test.mjs \
packages/analyzer/test/*.test.mjs \
packages/sync-encryptor/test/*.test.mjs \
packages/feature-extractor/test/*.test.mjs \
packages/license-client/test/*.test.mjs \
packages/mcp-proxy/test/*.test.mjs
# 单个软件包
cd packages/codex-provider && node --test test/**/*.test.mjs
```
297个测试，31个测试文件。 CLI流式测试套件中存在一个预先存在的计时问题（`tailSession`），仅在组合运行时表现出，在隔离运行时可靠通过。
---
## 已知限制
- **Codex钩子覆盖** - 目前仅限Bash。 文件写入、MCP调用和Web搜索是Codex钩子系统的上游空白（[#20204](https://github.com/openai/codex/issues/20204)）。
- **基于Cowork钩子的拦截不可用** - 所有Cowork版本当前忽略插件贡献的钩子（[#27398](https://github.com/anthropics/claude-code/issues/27398)，[#40495](https://github.com/anthropics/claude-code/issues/40495)）。 MCP代理方法为MCP工具调用提供完整的覆盖作为变通方法。
- **Grep/Glob文件读取计数** - 报告为调用计数，而不是单个文件计数。 钩子层无法观察到搜索实际打开了多少文件。
- **Codex事件的 `duration_ms`** - 从时钟时间计算，介于PreToolUse和PostToolUse shim调用之间，而不是Codex本身（Codex不发送此字段）。
- **双设置文件重复（克劳德代码）** - 如果 `.claude/settings.json` 和 `.claude/settings.local.json` 都包含欧姆诺德克斯钩子，事件将被重复计数。 仅使用 `settings.local.json` （`omnodex install claude-code` 默认）。
---
## 软件包布局
```
packages/
shared/ 事件模式 + 拦截器接口
event-log/ 追加JSONL事件日志（真相来源）
projection/ 投影器 + 读取模型存储（内存和SQLite）
analyzer/ 规则引擎：RuleDefinition、RuleEngine、RuleRegistry、
19个社区规则，涵盖8个类别，detectRisks()
hooks-provider/ ClaudeCodeInterceptor + MockInterceptor + claude-hook-shim
codex-provider/ CodexInterceptor + codex-hook-shim
antigravity-provider/ AntigravityInterceptor + antigravity-hook-shim
mcp-proxy/ MCP代理拦截器（位于代理和上游之间
MCP服务器）
sync-encryptor/ 基于零知识的AES-256-GCM同步加密（Argon2id KDF）
feature-extractor/ 用于云分析的隐私保护功能提取
license-client/ 许可证验证客户端（云API，缓存，离线回退）
cli/ omnodex CLI：install，uninstall，status，spike，
detect，replay，report，dashboard，mcp-proxy，license
多根仪表盘配置（config.ts）
```
---
## 许可证
欧姆诺德克斯采用双重许可：
- **开源：** [GNU Affero General Public License v3.0 (AGPL-3.0)](LICENSE)。 您可以在这些条款下使用、修改和分发欧姆诺德克斯。 如果您修改欧姆诺德克斯并将其作为网络服务提供，您必须在相同的许可证下共享您的修改。
- **商业：** 为需要非copyleft许可证的组织提供商业许可证，想要避免AGPL的源代码共享要求，或需要访问Hosted、Pro和Enterprise功能。 请参阅 [omnodex.com/licensing](https://omnodex.com/licensing) 获取详细信息。
在内部使用欧姆诺德克斯监控您自己的AI代理？ AGPL适用，但我们鼓励这种使用。 如果您的组织需要用于内部部署的非copyleft许可证， [联系我们](https://omnodex.com/contact) 获取商业许可证。
版权所有(c) 2026 欧姆诺德克斯有限责任公司。
