Getting Started
Working with Agents
Set up OpenApe agent gatekeeping for AI agents like OpenClaw.
Working with Agents
This guide sets up the three Agent Gate Applications to control what your AI agent can do. Every command the agent executes will require a grant — approved by a human.
The examples use OpenClaw as the agent, but the setup works with any agent that runs CLI commands.
Prerequisites
- A running OpenClaw instance
- An OpenApe IdP (use the public
https://id.openape.ator run your own) - Node.js 20+ and Rust toolchain (for escapes)
Step 1: Install the Agent Gate Applications
# grapes — the grant system
npm i -g @openape/grapes
# shapes — grant-constrained CLI execution
npm i -g @openape/shapes
# escapes — privilege escalation (requires Rust)
cd /tmp
git clone https://github.com/openape-ai/escapes.git
cd escapes
cargo build --release
sudo make install
Verify the installation:
grapes --version
shapes --version
escapes --help
Step 2: Register the Agent
Generate a key pair and enroll the OpenClaw agent with your IdP:
# Generate the agent's key pair
ssh-keygen -t ed25519 -f ~/.ssh/openclaw_agent -N ""
# Enroll the agent (admin operation)
curl -X POST https://id.openape.at/api/agent/enroll \
-H "Authorization: Bearer <your-management-token>" \
-H "Content-Type: application/json" \
-d "{\"email\":\"agent+openclaw@yourdomain.com\",\"name\":\"openclaw\",\"publicKey\":\"$(cat ~/.ssh/openclaw_agent.pub)\"}"
Agent enrollment is an admin operation that requires the Management Token. After enrollment, all further interaction uses
grapes.Step 3: Configure grapes
Create ~/.config/grapes/config.toml:
[defaults]
idp = "https://id.openape.at"
[agent]
key = "~/.ssh/openclaw_agent"
email = "agent+openclaw@yourdomain.com"
Login and verify:
grapes login
grapes whoami
# → agent+openclaw@yourdomain.com (agent) via https://id.openape.at
Step 4: Install Shapes Adapters
Install the adapters for the CLIs your OpenClaw agent uses:
# Browse available adapters
shapes adapter search --remote
# Install what you need
shapes adapter install gh # GitHub CLI
shapes adapter install az # Azure CLI
shapes adapter install exo # Exoscale CLI
shapes adapter install o365mail # Outlook Mail
shapes adapter install ls # ls
shapes adapter install cat # cat
shapes adapter install chmod # chmod
shapes adapter install chown # chown
List installed adapters:
shapes adapter list
Step 5: Configure escapes
Create /etc/openape/config.toml (as root):
audit_log = "/var/log/openape/audit.log"
[security]
allowed_issuers = ["https://id.openape.at"]
allowed_approvers = ["you@yourdomain.com"]
allowed_audiences = ["escapes"]
sudo mkdir -p /var/log/openape
sudo chmod 755 /var/log/openape
Step 6: Test the Flow
Normal operation (via shapes)
# See what permissions a command needs
shapes explain -- gh repo list myorg
# Request grant and execute
shapes request --approval once -- gh repo list myorg
# → Waiting for approval...
# In another terminal (as the approver):
grapes list --status pending
grapes approve <grant-id>
# → Command executes
Privilege escalation (via escapes)
# Request grant for a privileged command
grapes run escapes "apt-get install -y curl" --reason "Install dependency for agent"
# → Waiting for approval...
# → Approved → escapes executes with root privileges
How It Works with OpenClaw
Once configured, OpenClaw's agent operations flow through the gatekeeping trinity:
OpenClaw Agent
│
├─ Normal CLI commands ──→ shapes ──→ grant check ──→ execute
│ │
│ └─ Shapes Registry defines
│ which CLIs are available
│
└─ Privileged actions ───→ grapes ──→ grant request
│ │
│ └─ Human approves
│
└─→ escapes ──→ execute as root
- Every CLI execution goes through shapes — no blanket access
- Privileged operations require explicit escapes escalation
- All actions are audited in
/var/log/openape/audit.log - The human approver sees exactly what the agent wants to do before approving