APort Agent Guardrails 是一款针对 AI 智能体的确定性动作前授权工具，由 aporthq 发布，仓库地址为 https://github.com/aporthq/aport-agent-guardrails。其核心理念是：护栏在受支持的工具执行之前运行，因此提示注入无法绕过宿主发出的策略检查。
用途方面，该工具用于在 AI 智能体调用敏感工具（如文件、命令、外部调用）之前进行策略验证，减少提示注入与智能体错误决策带来的风险，将风险从运行时行为转移到策略配置层面。它提供两种使用方式：一是 Guardrails（CLI/安装器），运行安装器创建 passport 与配置；二是 Core（库），在应用中使用 OAPGuardrailProvider（参见 docs/PROVIDER.md），使每次工具调用都得到验证。每种语言有一个 provider（Python 与 TypeScript），可与任意框架配合。
主要能力包括：确定性执行（运行时钩子，而非提示指令）；默认失败关闭（验证失败阻止高风险动作）；显式发布模式（--enforcement=warn 记录已完成策略拒绝但允许框架动作，用于策略调优；--enforcement=observe 允许非强制的 APort 运行时/映射/API 失败并发出警告，便于采用）；可审计决策（每次允许/拒绝均带上下文记录）；开放标准产物（Open Agent Passport (OAP) v1.0 passport 与决策格式）；生产规模低延迟（云 API 验证 p50 约 53ms，N=1,000）。据资料，在实时对抗测试台中，宽松策略成功率为 74.6%，限制性 OAP 策略下为 0%（879 次顶级尝试）。
使用方式上，可通过 npm 运行：npx @aporthq/aport-agent-guardrails <framework>（或在提示时选择框架）。GitHub 仓库保护：npx @aporthq/aport-agent-guardrails github 会生成使用 GitHub Marketplace 中 aporthq/policy-verify-action@v1 的 GitHub Actions 工作流，是收集 AI 辅助仓库变更 OAP 证据的最快零密钥路径。保护分支的阻断式设置可使用 --mode hosted --branches main,staging，并添加 --block-protected-paths 使工作流、策略、包或发布面失败关闭。运行时钩子的 curl 安装：curl -fsSL https://aport.io/install.sh | bash -s -- claude-code。已托管 passport 可用 npx @aporthq/aport-agent-guardrails <framework> <agent_id>。更改执行模式但不重建 passport：npx @aporthq/aport-agent-guardrails mode claude-code --enforcement=warn。重置框架：npx @aporthq/aport-agent-guardrails reset claude-code --yes。
passport 设置选项包括：1) 立即创建托管 APort passport（推荐）；2) 使用已有托管 passport ID（粘贴 agent_id）；3) 创建本地 passport 文件（离线/本地 JSON passport）。对于非交互式安装，可使用 --non-interactive 并配合 --mode=local --output <path> 创建本地 passport；使用托管标志（如 --hosted 等）则创建托管 passport。
支持的框架与目标：CLI 当前支持 github、cursor、claude / claude-code、openclaw、langchain、crewai、deerflow、仅设置 n8n，以及 beta 命令钩子目标 codex、gemini、goose。opencode 被有意限制，直到通过已安装版本插件冒烟测试验证当前插件 API。Python 用户（LangChain/CrewAI/DeerFlow）可运行同一 CLI 进行向导与配置，然后按框架文档安装 Python 包。SDK 与中间件：Node 为 @aporthq/sdk-node、@aporthq/middleware-express；Python 为 aporthq-sdk-python、aporthq-middleware-fastapi。
前提条件：设置向导需要 Node 18+（或使用 Python CLI）。Claude Code、Cursor、Codex、Gemini CLI 与 Goose 钩子以及本地评估器需要 jq；若缺少 jq，钩子在 enforce、warn 和 observe 模式下会拒绝每次工具调用（APort: jq is required）。审计条目还需要宿主 PATH 中的 python3，否则 APort 会以 oap.missing_dependency 拒绝，而不是允许但无审计记录。无需克隆仓库。
护栏模式（本地 vs API）：Node 安装器（npx @aporthq/aport-agent-guardrails … / bin/agent-guardrails）的每个框架都接受相同标志：--mode=api（可选 --api-url，默认 https://api.aport.io）或 --mode=local，以及可选托管 ap_<hex> 参数（API 模式，无本地 passport）。该流程会写入 …/aport/guardrail-mode.env。Python 的 aport setup CLI 尚未解析这些标志。
执行模式：默认 enforce，APort 失败关闭，策略拒绝会阻止工具调用。--enforcement=warn 用于保守的仅报告发布：已完成的策略拒绝被记录但框架动作继续，而格式错误的钩子输入、缺失依赖、无效模式文件、未映射的有副作用工具以及评估器完整性失败仍会阻止。--enforcement=observe 用于采用优先的发布：APort 对策略拒绝和非强制的 APort 运行时/映射/API 失败返回 allow-with-warning，以便在调优 passport 和映射时不阻塞开发者。强制前提条件（如缺少 jq）仍会阻止；如果 APort 必须为 observe 模式适配器/API 失败创建合成审计条目，钩子还需要 python3，不安全或不可用的审计路径会以 oap.audit_unavailable 或 oap.missing_dependency 拒绝。Observe 不是安全执行模式。宿主可见性不同：Claude Code 显示 systemMessage 警告；Cursor 返回尽力而为的警告字段但可能不在 UI 中显示允许警告，因此以审计日志/状态输出为准。
更改执行模式：无需创建新 passport 或重装钩子，可使用 mode 命令。升级已安装运行时：重新运行未固定版本的 npx @aporthq/aport-agent-guardrails <framework> 安装器，会解析当前 npm 包、复用现有 passport 并替换框架钩子使用的稳定运行时副本。运行时钩子不会在工具调用期间检查 npm 更新，因此版本提示无法减慢或阻止智能体动作；企业部署可用 APORT_PACKAGE_VERSION 固定经审核的版本。
自定义目录安装：每个框架的配置目录可通过一个环境变量移动，安装器、mode 与 reset 命令以及 Python aport setup CLI 都会读取它（bin/lib/config.sh 中的 get_config_dir）。passport、guardrail-mode.env、运行时副本和审计日志都会落到 <dir>/aport/。例如 APORT_CLAUDE_CODE_CONFIG_DIR=/srv/agent/claude npx @aporthq/aport-agent-guardrails claude-code。对于 Codex、Gemini CLI 和 Goose，安装器会将变量写入钩子命令或包装脚本。对于 Claude Code 和 Cursor，设置文件仅存储钩子路径，钩子运行时读取该变量，因此需在宿主启动环境中 export；否则钩子回退到 ~/.claude 或 ~/.cursor，并在那里没有 passport 或模式文件时拒绝每次调用。Python 运行时包不读取这些变量；改为向 provider 或 callback 传递 config_path。若要将钩子指向配置目录之外的 passport，设置 APORT_PASSPORT_FILE 并同时设置 APORT_ALLOW_EXTERNAL_PASSPORT_FILE=1（资料在此处中断）。
