An open standard for integrating human decision-making directly into autonomous AI agent workflows using HTTP 202 responses.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install hitl-protocol
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 hitl-protocol 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 HITL Protocol?
HITL Protocol (Human in the Loop) is a specialized open standard designed to bridge the gap between autonomous agents and human oversight. It allows services to pause execution and request human input—such as approvals, selections, or form data—ensuring that critical decisions remain under human control. By leveraging Openclaw Skills like this, developers can prevent agent hallucinations or errors in high-stakes environments like financial transfers or system deployments.
The protocol is platform-agnostic, meaning it works seamlessly across various messaging interfaces like Telegram, Slack, and WhatsApp, as well as standard web browsers. It functions similarly to how OAuth handles authentication, but for human decisions, providing a clean separation between the service hosting the UI and the agent facilitating the communication.
HITL Protocol Use Cases
- Requesting human approval for sensitive financial transactions, insurance policy changes, or code deployments.
- Allowing users to select specific items from a list of search results or job listings generated by an agent.
- Collecting structured input via web forms when an agent lacks specific user data or preferences.
- Confirming irreversible actions such as deleting cloud resources or sending bulk marketing emails.
- Escalating error recovery to a human when an autonomous process fails due to an API error or unexpected state.
How HITL Protocol Works
- An agent sends a request to a service which determines that a human decision is required before proceeding.
- The service responds with an HTTP 202 Accepted status and a HITL JSON object containing a review URL and a polling endpoint.
- The agent presents the review prompt and link (or native messaging buttons) to the user via their preferred communication channel.
- The human interacts with the provided interface (browser or native buttons) to make a decision or provide requested data.
- The agent periodically polls the service status endpoint (or receives a webhook/SSE) to retrieve the structured result.
- Once the status is completed, the agent processes the result and resumes the autonomous workflow.
HITL Protocol Setup
To begin using HITL Protocol within your Openclaw Skills environment, you need to implement the standard HTTP 202 response pattern in your service or ensure your agent can parse the HITL object. No specific SDK is required.
For Services
Ensure your API returns the following structure when human input is needed:
{
"status": "human_input_required",
"hitl": {
"spec_version": "0.7",
"case_id": "review_abc123",
"review_url": "https://yourservice.com/review/abc123?token=xyz",
"poll_url": "https://api.yourservice.com/v1/reviews/abc123/status",
"type": "confirmation",
"prompt": "Confirm deployment of server-01?"
}
}
For Agents
Agents should detect the 202 status and forward the review_url to the user. Use the following bash command logic to test your integration:
# Use curl to simulate an agent polling for a decision result
curl -X GET https://api.yourservice.com/v1/reviews/review_abc123/status
HITL Protocol Data Schema & Taxonomy
The HITL Protocol organizes data through a standardized JSON schema that ensures compatibility across all Openclaw Skills and agents.
| Field | Type | Description |
|---|---|---|
| spec_version | string | The version of the HITL Protocol (e.g., "0.7"). |
| case_id | string | A unique, URL-safe identifier for the review instance. |
| review_url | URL | The HTTPS URL where the human performs the review. |
| poll_url | URL | The endpoint the agent hits to check the status of the decision. |
| type | enum | The category of review: approval, selection, input, confirmation, or escalation. |
| status | enum | The current state: pending, opened, in_progress, completed, expired, or cancelled. |
| result | object | The final decision data returned once the status is completed. |
HITL Protocol Advanced Features
- Channel-native inline actions for Telegram, Slack, and Discord via
submit_urlallowing users to decide without leaving the chat. - Multi-round edit cycles for iterative artifact reviews using
previous_case_idandnext_case_idlinks. - Support for real-time Server-Sent Events (SSE) and Webhook callbacks to reduce polling latency.
- Rich form field support including text, multiselect, date pickers, and custom validation rules for the input review type.
- Automated timeout handling with configurable
default_action(skip, approve, reject, or abort) for time-sensitive workflows. - Security via opaque tokens and SHA-256 hash storage to ensure only the intended user can provide input.
SKILL.md
Loading
Related Openclaw Skills
OpenClaw Update
A dedicated management skill for monitoring and applying version updates to the OpenClaw platform.
OpenClaw Update Skill
A specialized management tool for checking, applying, and verifying updates to the OpenClaw platform and its core components.
clawback
A secure Gmail proxy for AI agents that enforces compliance through policies, audit logging, and human-in-the-loop approvals.
Topic to Article Kit
A specialized research automation tool that converts AI topics into comprehensive writing packages including social evidence and structured outlines in Obsidian.
CV Builder
A sophisticated AI agent skill that generates professional resumes, interactive CVs, and 3D digital identities with built-in human-in-the-loop verification.
AdGuard Home Controller
A robust CLI tool for managing AdGuard Home DNS filtering, protection states, and domain rules via an intuitive HTTP API interface.
METADATA
Featured*
