🔱 Aquaman

🔱 唯一面向 AI 代理的独立凭证代理：自带保险库隔离与最小权限请求策略。你的密钥始终留在你原本存放它们的地方，绝不会进入代理的内存。兼容 1Password、keychain、keepassxc 以及许多其他工具。

你配置好了 Claude Code、OpenClaw 或 Hermes，现在却盯着 .env 文件，看着你宝贵的 API 密钥以明文形式躺在那里。你读过那些文章。你知道当代理被提示注入攻击时会发生什么。我们懂。

Aquaman 通过三层防御解决这个问题：

1. 进程隔离：API 密钥存放在独立的代理进程中，在出口处注入。代理持有的是一个标记，而非密钥，因此即使代理发生 RCE 也无法读取密钥。编码代理只能获得你声明的引用，一次一条命令。
2. 请求策略：按服务制定的规则控制代理可以调用哪些端点。阻止管理 API，防止删除操作，允许草稿但拒绝发送。被拒绝的请求永远不会获得真实凭证。
3. 防篡改审计：每一次凭证使用都会以 SHA-256 哈希链记录。你可以证明访问了什么，并在事后检测篡改。

选择你的路径

Aquaman 以四个协同工作的包发布，共享同一个保险库 + 同一个守护进程。只安装你需要的部分：

单个 aquaman CLI 统一呈现全部四个包：保险库和审计的顶层命令，OpenClaw 集成的 aquaman openclaw ...，编码代理集成的 aquaman coder ...（底层委托给 aquaman-coder），以及 Hermes Python 包的 aquaman hermes ...。

快速开始

aquaman help、aquaman doctor 是你的好帮手。

1. 仅保险库（只需代理 + 你的密钥）```bash

npm install -g aquaman-proxy aquaman setup # backend wizard + store keys aquaman daemon & # start the proxy aquaman credentials list # verify

代理监听 `~/.aquaman/proxy.sock`（UDS，`chmod 0o600`）。将任意工具指向 `http://aquaman.local/<service>/<path>`，代理便会从你选择的 vault 后端为该服务注入认证头。

### 2. OpenClaw Gateway```bash
openclaw plugins install aquaman-plugin           # 1. install plugin + proxy
openclaw aquaman setup                            # 2. backend + keys + plugin wire-up
openclaw                                          # 3. done - proxy starts automatically

故障排查：openclaw aquaman doctor。

直接使用 npm？ npm install -g aquaman-proxy && aquaman openclaw setup 效果相同——安装代理 CLI、存储你的密钥、将插件安装到 ~/.openclaw/extensions/aquaman-plugin/，并配置凭据（OpenClaw ≥ 2026.6.5 上使用 SecretRef 引用，旧版本上使用 auth-profiles.json 占位符）。

aquaman openclaw setup 将 models.providers.<svc>.baseUrl 和 channels.telegram.apiRoot 指向代理的环回监听器，因为 OpenClaw 的模型传输层及其各频道各自构建自己的 HTTP 客户端，绕过了 fetch 拦截器。除 Telegram 之外的频道不提供端点覆盖，因此它们的令牌会被存储和迁移，但不会在出口处注入（参见 packages/plugin/README.md）。在 openclaw.json 的插件配置下添加频道；支持的频道包括 Slack、Discord、Telegram、MS Teams、Matrix、LINE、Twitch、Twilio、BlueBubbles、Mattermost、Nostr、Tlon、Feishu、Google Chat、ElevenLabs、xAI、Cloudflare AI Gateway、Mistral、Hugging Face 等（共 25 个）。

3. AI 编码代理（目前为 Claude Code）```bash

npm install -g aquaman-proxy aquaman-coder # 1. install daemon + adapter aquaman setup # 2. vault wizard aquaman daemon & # 3. start the proxy

aquaman coder project add my-app --path ~/code/my-app
--env ANTHROPIC_API_KEY=aquaman://anthropic/api_key
--env GITHUB_TOKEN=aquaman://github/token # 4. declare a project aquaman coder setup claude-code # 5. wire Claude Code hooks aquaman doctor # 6. verify - should show both vault + coder green

**亲自体验一下（30 秒就能恍然大悟）：** 重启 Claude Code，在 `~/code/my-app` 中打开一个新会话，然后让 agent 运行：```
printenv | grep ANTHROPIC_API_KEY

你会在记录中看到这个：``` ANTHROPIC_API_KEY=[REDACTED:injected-value]

⏺ ANTHROPIC_API_KEY is set and available (injected via aquaman vault).

*子*进程看到的是真实密钥（你的测试、构建、MCP 服务器、导入脚本——任何真正需要它的东西都能正常工作）。而*代理*——那个决定在你的机器上运行什么代码的东西——永远看不到这个值，因此对话历史也看不到，模型提供商的日志也看不到，任何之后截取你终端屏幕截图的人也看不到。

**也可以从你自己的终端使用它。** 同一个包装器在没有代理的情况下也能工作。只需 `cd` 进入一个已覆盖的项目，并在命令前加上前缀：```bash
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py

同样的环境变量注入，同样的 stdout/stderr 脱敏。把它放进 Makefile 目标、shell 别名或 CI runner 中——任何你原本会使用 .env 文件的地方。

当 Claude Code 在 ~/code/my-app 中运行 Bash 工具时，aquaman 的 hook 会通过 updatedInput.command 重写命令，将其包装在 aquaman-coder exec 下。该包装器：

• 通过 broker（基于 UDS 的 POST /broker/resolve）解析每个 aquaman://service/key 引用。凭据仅为单条命令物化，而非在 agent 的整个生命周期内存在。
• 将 stdout/stderr 通过脱敏器管道处理，该脱敏器会为每个已解析的值前置一个基于值的模式：无论注入的是什么字符串，都会被脱敏，无论其形态如何（Atlassian token、Notion secret、内部 API key——它们都不需要匹配已知的提供商格式）。基于形态的通用模式（sk-ant-、ghp_、sk_live_、AKIA…、JWT、PEM 块、ATATT3xF…）仍会在之后运行，作为纵深防御，用于处理子进程暴露出的、我们并未注入的密钥。
• 在命令退出时进行清理。

Claude Code 沙箱： 它默认阻止 Unix socket，因此 aquaman coder setup claude-code 会在 macOS 上将代理 socket 加入允许列表（sandbox.network.allowUnixSockets）。Linux 和 WSL2 会忽略该列表，唯一的选择是 sandbox.network.allowAllUnixSockets: true，这会将所有 Unix socket 开放给沙箱化的命令。

4. Hermes（agent 主机）

Hermes 是一个外部（Python）主机，没有可注入的传输 hook，因此隔离在代理侧完成：代理暴露一个可选的、受 token 门控的 loopback 监听器，Hermes 通过其自身的环境变量指向它。```bash npm install -g aquaman-proxy # 1. install daemon aquaman setup # 2. vault wizard aquaman credentials add anthropic api_key sk-ant-... # 3. store a provider key

aquaman hermes setup # 4. enable loopback + write ~/.hermes/.env aquaman daemon & # 5. start the proxy (UDS + loopback) aquaman hermes doctor # 6. verify - listener + env + vault + Hermes

`aquaman hermes setup` 会启用回环监听器，生成每次安装唯一的令牌，并将一段由 aquaman 管理的配置块写入 `~/.hermes/.env`（遵循 `HERMES_HOME`）：原生的 `ANTHROPIC_BASE_URL`/`OPENAI_BASE_URL` 以及一个等于该令牌的占位 api_key。Hermes 将该令牌作为其提供商密钥发送；代理会剥离该令牌，注入你真实的 vault 凭据，并转发至上游。目前仅支持 LLM 提供商（Anthropic、OpenAI）。

**可选的会话内便捷功能** - Python 插件在 Hermes 内添加了一个 `/aquaman-status` 命令、一个 `aquaman_status` 工具，以及一个会话启动时的健康探测（不持有任何凭据）：```bash
pip install aquaman-hermes            # or: uv tool install aquaman-hermes
aquaman-hermes install                # drops the plugin into ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman

该插件还注册了一个 aquaman secret source（Hermes ≥ 0.18.1），用于管理诸如 GITHUB_TOKEN 之类的项目密钥。在 Hermes 的 config.yaml 中，将它们绑定到 secrets.aquaman.env 下，然后使用 aquaman broker allow aquaman://github/token 声明每个引用（自 v0.15.0 起为必需；aquaman hermes doctor 会列出你遗漏的引用）。与上面的 LLM 密钥不同，这些值确实会进入 Hermes 的环境变量。参见 packages/hermes/README.md。

工作原理```

Agent / OpenClaw / Coding Agent Aquaman Proxy ┌──────────────────────┐ ┌──────────────────────┐ │ │ │ │ │ ANTHROPIC_BASE_URL │═══ UDS / HTTP ════>│ Keychain / 1Pass / │ │ = aquaman.local │ │ Vault / Encrypted │ │ │<══════════════════ │ │ │ fetch() interceptor │═══ broker:resolve │ + Policy enforced │ │ (channel APIs) │ │ + Auth injected: │ │ │ │ header / url-path │ │ No credentials. │ ~/.aquaman/ │ basic / oauth │ │ No open ports. │ proxy.sock │ │ │ No keys to read. │ (chmod 0o600) │ │ └──────────────────────┘ └──┬─────────┬─────────┘ │ │ │ ▼ │ ~/.aquaman/audit/ │ (hash-chained) ▼ api.anthropic.com api.telegram.org slack.com/api …

1. **存储**：凭据存放在你已经在运行的 vault 后端中——无需自建 vault（Keychain、1Password、HashiCorp Vault、Bitwarden、KeePassXC、systemd-creds、encrypted-file）。
2. **策略**：代理在接触凭据*之前*先检查方法 + 路径规则。被拒绝的请求会收到 `403`，绝不会带上真实的认证头。
3. **注入**：代理查找凭据并在转发前添加认证头。25 个内置服务，4 种注入式认证模式（header、URL-path、HTTP Basic、OAuth）；第 5 种 `none` 仅用于静态存储（代理会拒绝流量）。
4. **Broker（coder + Hermes 密钥来源）**：`POST /broker/resolve` 为每次工具调用物化一个凭据，作用域限定为单条命令的环境变量。只有 `aquaman daemon` 提供该服务，且仅针对你声明过的引用（`projects.yaml` 或 `aquaman broker allow`）。OpenClaw 插件的代理从不提供该服务（v0.15.0+）。
5. **审计**：每次凭据使用都会以 SHA-256 哈希链记录日志。

在代理路径上，agent 看到的是一个本地端点加一个标记：`aquaman-proxy-managed` 占位符，或 loopback token，后者仅对你的本地代理有效。绝不会是真实密钥。在 coder 路径上，*子*命令会拿到声明的值，而 agent 看到的是脱敏后的输出。

## 安全模型

| 层级 | 作用 | 阻止什么 |
|---|---|---|
| **进程隔离** | 凭据位于独立进程中，通过 Unix socket（`chmod 0o600`）或受 token 门控的 loopback 监听器访问 | 被攻陷的 agent 无法读取被代理的密钥：地址空间不同 |
| **Broker 作用域** | 只有 `aquaman daemon` 会分发值，且仅针对你声明过的引用；OpenClaw 托管的代理从不分发（v0.15.0+） | agent 无法通过 socket 拉取任意 vault 条目 |
| **服务允许列表** | `proxiedServices` 控制 agent 可以访问哪些 API | agent 无法与你未授权的服务通信 |
| **请求策略** | 每个服务的方法 + 路径规则，在凭据注入前强制执行 | agent 可以访问 Anthropic 但无法访问其 admin API；可以起草邮件但无法发送 |
| **审计追踪** | 每次凭据使用都有 SHA-256 哈希链日志 | 事后取证、篡改检测、合规证据 |
| **按工具调用的 broker（coder）** | `aquaman-coder exec` 一次为一条命令物化凭据 | 凭据不会散落到 agent 的 shell 环境中 |
| **输出脱敏（coder）** | `aquaman-coder exec` 将 stdout/stderr 通过脱敏器管道处理，逐字擦除它刚刚注入的每个值——外加通用提供商模式作为兜底 | 即使是无固定形态的任意凭据也绝不会进入 agent 的对话记录 |

### 传输与访问控制

| 路径 | 传输 | 访问控制 |
|---|---|---|
| 编码 agent、任何能连接 socket 的客户端 | Unix socket `~/.aquaman/proxy.sock` | 文件权限（`0600`）：仅限以你的身份运行的进程 |
| Hermes（v0.13.0+）、OpenClaw 模型与 Telegram 流量（v0.15.0+） | Loopback TCP `127.0.0.1:<port>` | 每次安装生成的 token、常量时间校验、loopback 绑定 |

Hermes 和 OpenClaw 各自构建自己的 HTTP 客户端，无法连接 socket，因此它们使用监听器。其他一切都使用 socket。

该 token 是访问本地代理的能力凭证，而非凭据。每次安装时生成，存储在 `~/.aquaman/config.yaml`（`0600`）中，由宿主作为其提供商 api key 发送。代理会校验它、剥离它，并注入你的真实密钥。Telegram 没有认证头，因此在那里 token 改为搭载在 `/bot<TOKEN>` 路径段中。

权衡：任何本地进程都能访问 loopback 端口，包括其他用户，而 socket 的 `0600` 会将他们拒之门外。在那里 token 就是关卡，因此监听器在 `aquaman hermes setup` 或 `aquaman openclaw setup` 开启之前一直处于关闭状态。

### OpenClaw 2026.7.33+ 上的频道凭据

| 频道 | 是否通过代理出站 |
|---|---|
| Telegram | 是，自 v0.15.0 起 |
| 其他所有 | 否。仅限 vault 存储与迁移 |

每个频道按请求构建自己的 HTTP 客户端，因此在这些版本上插件的 `fetch` 拦截器不再能看到频道流量。路由某个频道需要来自宿主的端点覆盖，而 Telegram 是唯一具备该覆盖的频道：`aquaman openclaw setup` 将 `channels.telegram.apiRoot` 指向代理，并用 loopback token 替换 bot token。

对于其余频道，你的 token 留在 vault 中，但 OpenClaw 直接使用它，因此代理不在路径中，这些调用也不会被审计。`aquaman openclaw doctor` 会列出你配置的频道分别属于哪一组。模型提供商不受影响。

**同用户隔离做不到的事。** socket 的 `0o600` 能挡住其他用户，但挡不住以你的身份运行的其他进程。这样的进程可以在代理运行期间通过它发送请求（受请求策略约束，记录在审计日志中），并且可以获取你声明过的引用——这正是声明的含义。它无法读取代理注入的密钥。若需要更严格的边界，请以不同的 OS 用户身份或在沙箱中运行 agent。

详细模型——各集成的具体细节（HTTP 拦截器作用域、认证配置文件、扫描器发现、ClawScan 发布者说明）——见 [`packages/plugin/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/plugin/README.md) 和 [`packages/coder/README.md`](https://github.com/tech4242/aquaman/blob/main/packages/coder/README.md)。

### 合规态势

Aquaman 在 `test/compliance/` 下提供可运行的合规性测试，映射到：

- **MITRE ATLAS** v5.4.0：技术 AML.T0055、T0012、T0062、T0090、T0098（`test/compliance/atlas/`）
- **NIST SP 800-53 Rev 5**：IA-5、AC-3、AC-6、AU-2/9/10、SC-12/28、SI-10（`test/compliance/nist/`）

此外还有针对 CISA/Five-Eyes "Careful Adoption of Agentic AI Services"（2026 年 4 月）、CSA MAESTRO 以及 OWASP Top 10 for Agentic Applications 的对齐说明。这些测试作为 `npm test` 的一部分运行。映射关系见 [`docs/compliance/`](https://github.com/tech4242/aquaman/blob/main/docs/compliance)。


## 请求策略

OAuth 作用域无法区分"起草邮件"和"发送邮件"。两者都是 `gmail.send`。请求策略填补了这一空白。```yaml
# ~/.aquaman/config.yaml
policy:
  anthropic:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organizations/**"
        action: deny          # block admin/billing API
  openai:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/v1/organization/**"
        action: deny
      - method: DELETE
        path: "/v1/**"
        action: deny          # no deletions
  slack:
    defaultAction: allow
    rules:
      - method: "*"
        path: "/api/admin.*"
        action: deny          # Slack Web API admin methods
  gmail:
    defaultAction: allow
    rules:
      - method: POST
        path: "/gmail/v1/users/*/messages/send"
        action: deny          # drafts ok, sending blocked

• 路径是服务前缀之后的上游 API 完整路径：Slack 的 Web API 是 /api/<method>，Gmail 的是 /gmail/v1/...。v0.15.0 之前的预设使用 /admin.* 和 /v1/users/*/messages/send，这些从未匹配到真实流量。如果它们仍在你的配置中，aquaman doctor 会标记出来。
• 无策略 = 全部允许（向后兼容）
• 首个匹配生效：规则自上而下评估，未匹配的请求落到 defaultAction
• 拒绝先于认证：被阻止的请求永远不会获得真实凭据
• 路径通配符： * 匹配单个段内，** 匹配零个或多个段
• aquaman setup 为已存储的服务（anthropic、openai、slack、gmail）应用安全默认值。
• aquaman policy list / aquaman policy test <svc> <method> <path> 用于检查 / 试运行。

凭据后端

自带你的保险库——aquaman 没有内置存储。选择你已经在运行的后端；密钥留在那里，代理就地读取它们。

aquaman setup 会自动检测一个合理的默认值（macOS → keychain；Linux → 如果有 libsecret 则 keychain，否则如果 systemd ≥ 256 则 systemd-creds，否则 encrypted-file）。

encrypted-file 是没有原生密钥环的无头 Linux/CI 环境的最后手段。为了在 Linux 上获得更好的安全性，请安装 libsecret-1-dev（GNOME Keyring），使用 systemd-creds（TPM2 绑定），或使用 1Password/Vault。

凭据缓存（v0.13.1+）

具有每次访问成本的后端，如 1password（桌面应用模式下每次读取都需要生物识别提示）、bitwarden（约 1-2 秒的 CLI 启动）和 vault（一次 HTTP 往返），默认在守护进程的内存中缓存 15 分钟，因此繁忙的代理会话每个窗口解锁一次保险库，而不是每个请求解锁一次。其他后端已经很快或在内部缓存，因此默认对它们关闭缓存。通过 ~/.aquaman/config.yaml 中的 credentials.cacheTtlSeconds（或 AQUAMAN_CACHE_TTL）调整；0 禁用。

诚实的权衡：每次访问的生物识别提示是一种用户在场检查，而缓存在 TTL 窗口内移除了每次访问的在场要求。对于无人值守的代理，该提示永远不会被响应，因此保险库会被放弃，转而使用明文 .env，这严格来说更糟。缓存不会移动隔离边界：值只存在于代理进程中（它们已经在每个请求中经过那里），永远不会写入磁盘，并且当你通过 aquaman credentials add 轮换时会立即失效。写入始终进入你的保险库。已在 test/compliance/cache-residency.test.ts 中进行一致性测试。对于 1Password 的零提示，请使用限定到 aquaman 保险库的服务账户；aquaman doctor 会指引你到那里。

许可证

MIT - 参见 LICENSE。