aport-guardrail

TotalClaw 作者 totalclaw

AI 代理的行动前授权。在运行每个工具（shell、消息传递、git、MCP、数据导出）之前验证权限。适用于 OpenClaw、IronClaw、PicoClaw。 APort策略引擎确定性地允许或拒绝每个工具调用；代理无法跳过它。

安装 / 下载方式

TotalClaw CLI推荐

totalclaw install totalclaw:totalclaw~uchibeke-apoer-agent-guardrail

cURL直接下载，无需登录

curl -fsSL https://skills.taituai.com/api/skills/totalclaw%3Atotalclaw~uchibeke-apoer-agent-guardrail/file -o uchibeke-apoer-agent-guardrail.md

# APort Agent Guardrail

Pre-action authorization for AI agents: every tool call is checked **before** it runs. Works with OpenClaw, IronClaw, PicoClaw, and compatible frameworks. Run the installer once; the OpenClaw plugin then enforces policy on every tool call automatically. You do **not** run the guardrail script yourself.

> Requires: Node 18+, jq. Install with `npx @aporthq/agent-guardrails` or `./bin/openclaw` from the repo.

## Installation

```bash
# Recommended (no clone needed)
npx @aporthq/agent-guardrails

# Hosted passport: skip the wizard by passing agent_id from aport.io
npx @aporthq/agent-guardrails <agent_id>
```

Get a Hosted Passport **agent_id** at [aport.io](https://aport.io/builder/create/) after creating a passport there. __*OPTIONAL*__

From the repo (clone first): [github.com/aporthq/aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails) — then run `./bin/openclaw` or `./bin/openclaw <agent_id>` from the repo root. Full guides: [QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md) · [Hosted passport setup](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md).

You can preview your local passport at `~/.openclaw/aport/passport.json` (or `<config-dir>/aport/passport.json` if you chose a different config dir; legacy installs may use `<config-dir>/passport.json`).

The installer is interactive: it sets your config dir, passport (local or hosted), installs the APort OpenClaw plugin, writes config, and installs wrappers. **After it finishes, nothing else is required**—start OpenClaw (or use the running gateway); the plugin enforces before every tool call.

Wrappers (default config dir `~/.openclaw`): `~/.openclaw/.skills/aport-guardrail.sh` (local), `~/.openclaw/.skills/aport-guardrail-api.sh` (API/hosted). The plugin uses these; you don’t call them unless testing.

## Usage

**Normal use:** Run the installer once. After that, nothing to run manually—the plugin enforces before each tool call automatically.

**Optional — direct script calls** (e.g. testing or other automations):

```bash
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"ls"}'
~/.openclaw/.skills/aport-guardrail.sh messaging.message.send '{"channel":"whatsapp","to":"+15551234567"}'
```

- Exit 0 = ALLOW (tool may proceed)
- Exit 1 = DENY (see `<config-dir>/aport/decision.json` or `<config-dir>/decision.json` for reason codes)

For API mode / hosted passports:

```bash
APORT_API_URL=https://api.aport.io ~/.openclaw/.skills/aport-guardrail-api.sh system.command.execute '{"command":"ls"}'
```

## Tool name mapping

| When you're about to…        | Use tool_name               |
|------------------------------|-----------------------------|
| Run shell commands           | `system.command.execute`    |
| Send WhatsApp/email/etc.     | `messaging.message.send`    |
| Create/merge PRs             | `git.create_pr`, `git.merge`|
| Call MCP tools               | `mcp.tool.execute`          |
| Export data / files          | `data.export`               |

Context must be valid JSON, e.g. `'{"command":"ls"}'` or `'{"channel":"whatsapp","to":"+1..."}'`.

## Why this skill?

- **Deterministic** – runs in `before_tool_call`; the agent cannot skip it.
- **Structured policy** – backed by [Open Agent Passport (OAP) v1.0](https://github.com/aporthq/aport-spec/tree/main) and policy packs.
- **Fail-closed** – if the guardrail errors, the tool is blocked.
- **Audit-ready** – decisions are logged (local JSON or APort API for signed receipts).

Pair it with other threat-detection tooling if needed; enforce policy through this guardrail so unsafe actions never run.

## Docs

**This repo:** [QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md) · [Hosted passport](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md) · [Tool / policy mapping](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/TOOL_POLICY_MAPPING.md)

**OpenClaw:** [CLI: skills](https://docs.openclaw.ai/cli/skills) · [Skills](https://docs.openclaw.ai/tools/skills) · [Skills config](https://docs.openclaw.ai/tools/skills-config) · [ClawHub](https://docs.openclaw.ai/tools/clawhub)

---

## 中文说明

# APort 代理护栏（Agent Guardrail）

为 AI 代理提供行动前授权：每一次工具调用都会在运行**之前**接受检查。可与 OpenClaw、IronClaw、PicoClaw 及兼容框架配合使用。只需运行一次安装程序；之后 OpenClaw 插件就会在每次工具调用时自动强制执行策略。你**无需**自己运行护栏脚本。

> 要求：Node 18+、jq。使用 `npx @aporthq/agent-guardrails` 安装，或从仓库运行 `./bin/openclaw`。

## 安装

```bash
# Recommended (no clone needed)
npx @aporthq/agent-guardrails

# Hosted passport: skip the wizard by passing agent_id from aport.io
npx @aporthq/agent-guardrails <agent_id>
```

在 [aport.io](https://aport.io/builder/create/) 创建 passport 后，可在那里获取托管式 Passport 的 **agent_id**。__*可选*__

从仓库安装（先克隆）：[github.com/aporthq/aport-agent-guardrails](https://github.com/aporthq/aport-agent-guardrails) —— 然后从仓库根目录运行 `./bin/openclaw` 或 `./bin/openclaw <agent_id>`。完整指南：[QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md) · [Hosted passport setup](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md)。

你可以在 `~/.openclaw/aport/passport.json` 预览本地 passport（如果你选择了不同的配置目录，则为 `<config-dir>/aport/passport.json`；旧版安装可能使用 `<config-dir>/passport.json`）。

安装程序是交互式的：它会设置你的配置目录、passport（本地或托管）、安装 APort OpenClaw 插件、写入配置并安装 wrapper。**安装完成后，无需再做任何事情**——启动 OpenClaw（或使用正在运行的网关）；插件会在每次工具调用前强制执行。

Wrapper（默认配置目录 `~/.openclaw`）：`~/.openclaw/.skills/aport-guardrail.sh`（本地）、`~/.openclaw/.skills/aport-guardrail-api.sh`（API/托管）。插件会使用它们；除非测试，否则你无需调用它们。

## 用法

**常规使用：** 运行一次安装程序。之后无需手动运行任何东西——插件会在每次工具调用前自动强制执行。

**可选 —— 直接调用脚本**（例如用于测试或其他自动化）：

```bash
~/.openclaw/.skills/aport-guardrail.sh system.command.execute '{"command":"ls"}'
~/.openclaw/.skills/aport-guardrail.sh messaging.message.send '{"channel":"whatsapp","to":"+15551234567"}'
```

- 退出码 0 = ALLOW（工具可以继续）
- 退出码 1 = DENY（参见 `<config-dir>/aport/decision.json` 或 `<config-dir>/decision.json` 了解原因代码）

对于 API 模式 / 托管 passport：

```bash
APORT_API_URL=https://api.aport.io ~/.openclaw/.skills/aport-guardrail-api.sh system.command.execute '{"command":"ls"}'
```

## 工具名称映射

| 当你即将…                    | 使用 tool_name              |
|------------------------------|-----------------------------|
| 运行 shell 命令              | `system.command.execute`    |
| 发送 WhatsApp/邮件等         | `messaging.message.send`    |
| 创建/合并 PR                 | `git.create_pr`, `git.merge`|
| 调用 MCP 工具                | `mcp.tool.execute`          |
| 导出数据 / 文件              | `data.export`               |

Context 必须是有效的 JSON，例如 `'{"command":"ls"}'` 或 `'{"channel":"whatsapp","to":"+1..."}'`。

## 为什么使用本技能？

- **确定性** —— 运行于 `before_tool_call`；代理无法跳过它。
- **结构化策略** —— 以 [Open Agent Passport (OAP) v1.0](https://github.com/aporthq/aport-spec/tree/main) 和策略包为支撑。
- **失败即关闭（Fail-closed）** —— 如果护栏出错，工具将被阻止。
- **可审计（Audit-ready）** —— 决策会被记录（本地 JSON 或 APort API 提供签名回执）。

如有需要，可将其与其他威胁检测工具配合使用；通过本护栏强制执行策略，使不安全的操作永远不会运行。

## 文档

**本仓库：** [QuickStart: OpenClaw Plugin](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/QUICKSTART_OPENCLAW_PLUGIN.md) · [Hosted passport](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/HOSTED_PASSPORT_SETUP.md) · [Tool / policy mapping](https://github.com/aporthq/aport-agent-guardrails/blob/main/docs/TOOL_POLICY_MAPPING.md)

**OpenClaw:** [CLI: skills](https://docs.openclaw.ai/cli/skills) · [Skills](https://docs.openclaw.ai/tools/skills) · [Skills config](https://docs.openclaw.ai/tools/skills-config) · [ClawHub](https://docs.openclaw.ai/tools/clawhub)