A security-first proxy that enables AI agents to access third-party APIs and Git repositories through human-in-the-loop Telegram approvals.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install permissions-broker
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install permissions-broker using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Permissions Broker?
The Permissions Broker serves as the default mechanism for external data access within Openclaw Skills when local credentials are unavailable. It functions as an approval-gated proxy, allowing AI agents to propose specific upstream requests (URL, method, and body) which the user must then authorize via a Telegram interface. This architecture ensures that sensitive actions remain under direct human control while providing agents with the connectivity they need.
By leveraging this skill, Openclaw Skills can interact with major providers including Google (Drive, Docs, Sheets), GitHub, iCloud (CalDAV), and Spotify without the agent ever handling long-term user credentials. The broker manages the complex OAuth flows and credential injection, presenting a unified and secure API for the agent to consume data and perform actions across the web.
Permissions Broker Use Cases
- Automating Google Drive file searches and reading spreadsheet data for analysis.
- Managing GitHub workflows, such as creating pull requests, issues, or comments.
- Synchronizing iCloud calendar events and reminders via CalDAV integration.
- Executing secure Git operations like cloning, fetching, and pushing to remote repositories without local SSH keys.
- Controlling Spotify playback and managing playlists through natural language commands.
How Permissions Broker Works
- The agent identifies a required external action and collects the necessary parameters, such as the target upstream URL.
- The agent calls the broker API to create a proxy request, including a consent hint that explains the purpose to the user.
- The user receives a notification in Telegram and chooses to approve or deny the specific request.
- The agent polls the broker status endpoint (usually for 30 seconds) awaiting the user's decision.
- Upon approval, the agent calls the execution endpoint once to retrieve the data from the upstream service.
- The agent parses the returned data and proceeds with its task, while the broker ensures the request cannot be executed a second time.
Permissions Broker Setup
To integrate this skill with your Openclaw Skills environment, follow these steps:
- Generate a broker API key by messaging the Telegram bot with the command:
/key <your_key_name>
- Link your service providers (e.g., Google or GitHub) in Telegram using:
/connect <provider_name>
- Store your API key in your local environment variables or secrets store:
export PB_API_KEY='your_secret_key_here'
- Configure the agent to use the broker's base URL for all external API proxying.
Permissions Broker Data Schema & Taxonomy
The Permissions Broker organizes its operations around request objects and session metadata. The following table outlines the core data structure for proxy requests:
| Attribute | Description |
|---|---|
upstream_url |
The destination HTTPS URL for the external service. |
method |
The HTTP verb used (GET, POST, PUT, PATCH, DELETE). |
consent_hint |
A plain-language string explaining the request to the user. |
status |
The lifecycle state: PENDING_APPROVAL, APPROVED, EXECUTED, or DENIED. |
request_id |
A unique identifier used for polling and execution. |
Constraints: The broker enforces a 256 KiB cap on request bodies and a 1 MiB cap on upstream responses to ensure performance and security.
Permissions Broker Advanced Features
- Smart HTTP Git Proxy: Enables secure git clone, fetch, and push operations through session-scoped remote URLs.
- Idempotency Support: Uses idempotency keys to prevent duplicate requests during network retries.
- Custom Rendering Hints: Supports timezone-aware headers (e.g., x-pb-timezone) to display human-friendly timestamps in Telegram approvals.
- Automated Polling Logic: Built-in patterns for agents to await user feedback before proceeding with execution.
- Multi-Provider Allowlist: Centralized management for accessing Google APIs, GitHub API, Spotify, and iCloud CalDAV hosts.
SKILL.md
Loading
Related Openclaw Skills
Open Wallet
A bridge for AI agents to generate shareable links that allow users to securely execute blockchain transactions or sign messages using their own wallets.
Linear
Integrate Linear project management into your agentic workflow to automate issue tracking, notification handling, and team synchronization.
agentmail-cli
A command-line interface for the AgentMail API to manage disposable inboxes and automate email communication.
WeirdFi Arena AI Gaming Suite
A competitive gaming platform where AI agents test their logic and strategy through Minesweeper, Checkers, and commit-reveal duels.
Simple HTTP
A lightweight, zero-dependency Node.js HTTP client for making resilient API requests with automatic retries and graceful error handling.
Paper Parse
A sophisticated academic analysis tool that generates both deep technical reports and concise logical summaries for any scientific paper.