aquaman v0.14.1
🔱 唯一独立的AI代理凭据代理：自带保险库隔离和最小权限请求策略。您的密钥仍留在您原本存放的地方，绝不会进入代理的内存。兼容 1Password、keychain、keepassxc 等众多工具。
🔱 Aquaman
🔱 唯一独立的AI代理凭证代理：自带保险库隔离与最小权限请求策略。你的密钥始终保存在你已存放的位置，永远不会进入代理的内存。兼容 1Password、keychain、keepassxc 等众多工具。
你配置好了 Claude Code、OpenClaw 或 Hermes，然后盯着那些明文存放宝贵 API 密钥的 .env 文件。你读过相关文章，知道当代理遭受提示注入时会发生什么。我们理解。
Aquaman 通过三层防御机制解决这一问题：
- 进程隔离：API 密钥位于独立的代理进程中。代理永远看不到它们。即使代理中出现远程代码执行，也无法触及凭证。它们处于不同的地址空间。
- 请求策略：针对具体服务定义规则，控制代理可以调用的 端点。阻止管理 API，防止删除操作，允许草稿但禁止发送。被拒绝的请求永远不会获得真实凭证。
- 防篡改审计：每次凭证使用都通过 SHA-256 哈希链记录。你可以证明哪些凭证被访问过，并在事后检测篡改。
选择你的路径
Aquaman 作为四个协调的包发布，共享一个保险库和一个守护进程。仅安装你需要的部分：
| 包 | 功能 | 安装场景 |
|---|---|---|
aquaman-proxy | 核心：保险库、守护进程、审计、策略、CLI。每个人都需要的部分。 | 始终需要。 |
aquaman-plugin | OpenClaw 网关适配器。在网关启动时生成代理；拦截频道流量；覆盖5种认证模式下的25个内置服务。 | 如果你运行 OpenClaw 网关。也可在 https://clawhub.ai/plugins/aquaman-plugin 获取 |
aquaman-coder | AI 编码代理适配器。在每次 Bash 工具调用时解析项目范围内的 aquaman://service/key 引用。 | 如果你使用 Claude Code（当前）—— Codex / OpenCode / Cursor 计划中。 |
aquaman-hermes | Hermes 代理主机插件（Python，发布在 PyPI 上）。通过其原生的 ANTHROPIC_BASE_URL/OPENAI_BASE_URL 将 Hermes 指向一个可选的、令牌保护的环回监听器；在会话中添加 /aquaman-status 命令、工具和健康探测。隔离在代理端进行；插件不持有凭证。 | 如果你运行 Hermes 代理主机。pip install aquaman-hermes |
单个 aquaman CLI 覆盖所有四个包：顶层命令用于保险库和审计，aquaman openclaw ... 用于 OpenClaw 集成，aquaman coder ... 用于编码代理集成（底层委托给 aquaman-coder），以及 aquaman hermes ... 用于 Hermes Python 包。
快速开始
aquaman help、aquaman doctor 是你的好帮手。
1. 仅保险库（代理 + 你的秘密）
npm install -g aquaman-proxy
aquaman setup # 后端向导 + 存储密钥
aquaman daemon & # 启动代理
aquaman credentials list # 验证
代理监听在 ~/.aquaman/proxy.sock（UDS，chmod 0o600）。将任何工具指向 http://aquaman.local/<service>/<path>，代理便会从你选择的保险库后端为该服务注入认证头。
2. OpenClaw 网关
openclaw plugins install aquaman-plugin # 1. 安装插件 + 代理
openclaw aquaman setup # 2. 后端 + 密钥 + 插件接线
openclaw # 3. 完成 - 代理自动启动
故障排查：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 占位符。
插件的 HTTP 拦截器仅重定向其 services 配置中服务的流量（默认 Anthropic + OpenAI）。在 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）
npm install -g aquaman-proxy aquaman-coder # 1. 安装守护进程 + 适配器
aquaman setup # 2. 保险库向导
aquaman daemon & # 3. 启动代理
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. 声明项目
aquaman coder setup claude-code # 5. 配置 Claude Code 钩子
aquaman doctor # 6. 验证 - 应显示保险库和编码器均正常
亲眼看看（30秒醍醐灌顶）： 重新启动 Claude Code，在 ~/code/my-app 内打开一个新会话，并让代理运行：
printenv | grep ANTHROPIC_API_KEY
你会在记录中看到：
ANTHROPIC_API_KEY=[REDACTED:injected-value]
⏺ ANTHROPIC_API_KEY 已设置并可用（通过 aquaman 保险库注入）。
子进程看到了真实的密钥（你的测试、构建、MCP 服务器、导入脚本——任何真正需要它的东西都能正常工作）。而代理——那个决定在你的机器上运行什么代码的东西——永远看不到这个值，因此对话历史、模型提供商的日志、以及任何后来截取你终端截图的人都无法看到。
也可以从你自己的终端使用它。 同样的包装器无需代理即可工作。只需 cd 进入一个被覆盖的项目，并在命令前加上前缀：
cd ~/code/
aquaman-coder exec -- python app/scripts/import.py
相同的环境注入，相同的对 stdout/stderr 的编辑。可以将其放入 Makefile 目标、shell 别名或 CI 运行器中——任何你原本会使用 .env 文件的地方。
当 Claude Code 在 ~/code/my-app 中运行 Bash 工具时，aquaman 的钩子通过 updatedInput.command 重写命令，将其包装在 aquaman-coder exec 下。该包装器：
- 通过代理（通过 UDS 的
POST /broker/resolve）解析每个aquaman://service/key引用。凭证为单个命令物化，而非代理的整个生命周期。 - 将 stdout/stderr 通过一个编辑管道，该编辑为每个已解析的值预置基于值的模式：无论注入的字符串是什么形状，都会被编辑（Atlassian 令牌、Notion 秘密、内部 API 密钥——它们都不需要匹配已知的提供商格式）。通用形状模式（sk-ant-、ghp_、sk_live_、AKIA…、JWT、PEM 块、ATATT3xF…）仍然作为纵深防御运行，以防止子进程暴露我们未注入的秘密。
- 在命令退出时进行清理。
4. Hermes（代理主机）
Hermes 是一个外部（Python）主机，没有可注入的传输钩子，因此隔离在代理端进行：代理暴露一个可选的、令牌保护的环回监听器，Hermes 通过其自身的环境变量指向该监听器。
npm install -g aquaman-proxy # 1. 安装守护进程
aquaman setup # 2. 保险库向导
aquaman credentials add anthropic api_key sk-ant-... # 3. 存储提供商密钥
aquaman hermes setup # 4. 启用环回 + 写入 ~/.hermes/.env
aquaman daemon & # 5. 启动代理（UDS + 环回）
aquaman hermes doctor # 6. 验证 - 监听器 + 环境变量 + 保险库 + Hermes
aquaman hermes setup 启用环回监听器，生成一个每次安装唯一的令牌，并将一个 aquaman 管理的块写入 ~/.hermes/.env（遵循 HERMES_HOME）：原生的 ANTHROPIC_BASE_URL/OPENAI_BASE_URL 加上一个等于该令牌的占位符 api_key。Hermes 将该令牌作为其提供商密钥发送；代理剥离它，注入你的真实保险库凭证，并转发上游。目前仅限 LLM 提供商（Anthropic、OpenAI）。
可选的会话内糖分 - Python 插件在 Hermes 内部添加了一个 /aquaman-status 命令、一个 aquaman_status 工具和一个会话启动健康探测（不持有凭证）：
pip install aquaman-hermes # 或：uv tool install aquaman-hermes
aquaman-hermes install # 将插件放入 ~/.hermes/plugins/aquaman/
hermes plugins enable aquaman
工作原理
代理 / OpenClaw / 编码代理 Aquaman 代理
┌──────────────────────┐ ┌──────────────────────┐
│ │ │ │
│ ANTHROPIC_BASE_URL │═══ UDS / HTTP ════>│ 钥匙串 / 1Pass / │
│ = aquaman.local │ │ 保险库 / 加密文件 │
│ │<══════════════════ │ │
│ fetch() 拦截器 │═══ broker:resolve │ + 策略强制执行 │
│ （频道 API） │ │ + 认证注入： │
│ │ │ 头 / URL 路径 │
│ 无凭证。 │ ~/.aquaman/ │ 基本 / OAuth │
│ 无开放端口。 │ proxy.sock │ │
│ 无可窃取之物。 │ (chmod 0o600) │ │
└──────────────────────┘ └──┬─────────┬─────────┘
│ │
│ ▼
│ ~/.aquaman/audit/
│ (哈希链)
▼
api.anthropic.com
api.telegram.org
slack.com/api …
- 存储：凭证存在于你已经运行的保险库后端——没有内部保险库（钥匙串、1Password、HashiCorp Vault、Bitwarden、KeePassXC、systemd-creds、加密文件）。
- 策略：代理在接触凭证之前检查方法 + 路径规则。被拒绝的请求返回
403，永远不会获得真实认证头。 - 注入：代理查找凭证，并在转发前添加认证头。25个内置服务，4种注入认证模式（头、URL路径、HTTP基本认证、OAuth）；第五种
none仅用于静态存储（代理拒绝流量）。 - 代理（编码器路径）：
POST /broker/resolve为每个工具调用物化凭证，限定在单个命令的环境内，然后过期。 - 审计：每次凭证使用都通过 SHA-256 哈希链记录。
代理只看到一个哨兵主机名（aquaman.local）或一个占位符标记（aquaman-proxy-managed）。它永远看不到真实密钥，也没有 TCP 端口开放供其他进程探测。
安全模型
| 层级 | 功能 | 阻止的威胁 |
|---|---|---|
| 进程隔离 | 凭证处于独立进程，通过 Unix 域套接字连接（chmod 0o600） | 受损代理无法读取密钥——不同的地址空间，无 TCP 端口可供探测 |
| 服务白名单 | proxiedServices 控制代理可以访问的 API | 代理无法与你未授权的服务通信 |
| 请求策略 | 每个服务的方法 + 路径规则，在凭注入前执行 | 代理可以访问 Anthropic，但不能访问其管理 API；可以起草邮件但不能发送 |
| 审计追踪 | 每次凭证使用都有 SHA-256 哈希链日志 | 事后取证、篡改检测、合规证据 |
| 每次工具调用的代理（编码器） | aquaman-coder exec 一次只为一个命令物化凭证 | 凭证不会在代理的 shell 环境中扩散 |
| 输出编辑（编码器） | aquaman-coder exec 将 stdout/stderr 通过一个编辑管道，该编辑器逐字清除它刚注入的每个值——再加上通用提供商模式作为回退 | 即使是任意形状的凭证也永远不会到达代理记录 |
详细模型——每个集成的具体信息（HTTP 拦截器范围、认证配置文件、扫描器发现、ClawScan 发布者说明）——位于 packages/plugin/README.md 和 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/五眼联盟“谨慎采用 Agentic AI 服务”（2026年4月）、CSA MAESTRO 以及 OWASP Agentic 应用 Top 10 的对齐说明。这些测试作为 npm test 的一部分运行。参见 docs/compliance/ 了解映射关系。
请求策略
OAuth 作用域无法区分“起草一封邮件”和“发送一封邮件”。两者都是 gmail.send。请求策略填补了这一空白。
# ~/.aquaman/config.yaml
policy:
anthropic:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organizations/**"
action: deny # 阻止管理/计费 API
openai:
defaultAction: allow
rules:
- method: "*"
path: "/v1/organization/**"
action: deny
- method: DELETE
path: "/v1/**"
action: deny # 禁止删除
slack:
defaultAction: allow
rules:
- method: "*"
path: "/admin.*"
action: deny
gmail:
defaultAction: allow
rules:
- method: POST
path: "/v1/users/*/messages/send"
action: deny # 草稿可以，发送被阻止
- 无策略 = 允许所有（向后兼容）
- 首次匹配获胜：规则从上到下评估，未匹配的请求回退到
defaultAction - 拒绝发生在认证之前：被阻止的请求永远不会获得真实凭证
- 路径通配符：
*匹配段内的任意内容，**匹配零个或多个段 aquaman setup为存储的服务（anthropic、openai、slack、gmail）应用安全默认值。aquaman policy list/aquaman policy test <svc> <method> <path>用于检查/试运行。
凭证后端
自带保险库——aquaman 没有内置存储。选择你已在运行的后端；秘密留在那里，代理就地读取。
| 后端 | 适用场景 | 配置 |
|---|---|---|
keychain | macOS 本地开发（默认） | 开箱即用 |
encrypted-file | Linux、WSL2、CI/CD | AES-256-GCM，密码保护 |
keepassxc | 已有 KeePass 用户 | 设置 AQUAMAN_KEEPASS_PASSWORD 或密钥文件 |
1password | 团队凭证共享 | brew install 1password-cli && op signin——对于无人值守代理，使用服务账号（OP_SERVICE_ACCOUNT_TOKEN） |
vault | 企业秘密管理 | 设置 VAULT_ADDR + VAULT_TOKEN |
systemd-creds | 使用 systemd ≥ 256 的 Linux | TPM2 支持，无需 root |
bitwarden | Bitwarden 用户 | bw login && export BW_SESSION=$(bw unlock --raw) |
aquaman setup 自动检测合理的默认值（macOS → keychain；Linux → 如果 libsecret 可用则 keychain，否则如果 systemd ≥ 256 则 systemd-creds，否则 encrypted-file）。
encrypted-file 是无原生密钥环的无头 Linux/CI 环境中的最后手段。为了提高 Linux 上的安全性，请安装 libsecret-1-dev（GNOME 密钥环）、使用 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。