Documentation — Agent Constitution

Overview Installation Pairing Directives Checking Directives Vault Health Data Drift Testing Encryption File Integrity API Reference

Overview

Agent Constitution lets you define behavioral rules for your AI agent in plain English. Before any restricted action, the agent checks your rules and waits for your approval via push notification.

The system has three parts:

iOS App — where you define rules, approve actions, and view audit logs
Relay Server — a stateless message queue between your agent and phone
Agent Skill — bash scripts your agent uses to check rules and request approvals

Key principle: Rules are stored on your phone, not the server. The relay just passes messages — it can't see or modify your rules.

Installation

Agent Constitution is distributed as a skill package for OpenClaw.

Requirements

OpenClaw — Install from openclaw.ai
Agent Constitution iOS App — Download from the App Store
jq — brew install jq (macOS) or apt install jq (Linux)
bash — Version 4+ recommended

Install the Skill

# Navigate to your OpenClaw workspace skills directory
cd $WORKSPACE/skills

# Clone the skill package
git clone https://github.com/arunrlverma/agent-constitution.git agent-constitution

# Run setup (patches AGENTS.md and HEARTBEAT.md)
bash agent-constitution/scripts/setup.sh

$WORKSPACE is your OpenClaw workspace directory (e.g., ~/workspace). The setup script will add constitution checking to your agent's boot sequence.

What Gets Installed

Component	Purpose
`SKILL.md`	Instructions your agent reads at session start
`scripts/`	Bash scripts for pairing, sync, approvals, vault, drift tests
`active-rules.json`	Synced rules from your iPhone (created after pairing)

Pairing Your iPhone

After installing the app on your iPhone, tap "Pair Agent" to get a code like CLAW-A1B2C3D4.

# Pair with your iPhone
bash skills/agent-constitution/scripts/pair.sh CLAW-A1B2C3D4

This creates ~/.secrets/relay4agents.env with your credentials:

RELAY_URL=https://clawd-relay.fly.dev
CHANNEL_ID=your-channel-id
CHANNEL_TOKEN=your-secret-token

Fast-Sync Mode: After pairing, the agent enters fast-sync mode (2-minute heartbeat) for 24 hours. This quickly syncs rules and health data during initial setup, then reverts to 30-minute intervals.

Defining Directives

Directives are defined in the iOS app. Write them in plain English — describe what actions should require your approval.

Example Directives

The app includes 15 prebuilt templates across 6 categories, or you can write your own:

"Ask before sending work emails"
"Require approval for any purchase"
"Never post to social media without confirmation"
"Ask before running rm or delete commands"
"Require approval to unlock doors"

Rule Format

Internally, rules use a structured format that helps agents match them consistently:

{
  "title": "Ask before sending work emails",
  "description": "TRIGGER: email, send, draft, compose. ACTION: Ask for approval first. CONSTRAINT: Do not send until approved.",
  "category": "communication",
  "enabled": true
}

You don't need to write this format — the app handles it. Just describe your rule in plain English.

Checking Directives

Before performing any restricted action, your agent must check against active directives and wait for approval.

Using the Script

bash skills/agent-constitution/scripts/check-constitution.sh \
  --rule "Ask before sending work emails" \
  --action "Send email to team@company.com about project update" \
  --reason "User asked me to send the weekly status update"

Parameters

Parameter	Description
`--rule`	The rule title (match exactly from active-rules.json)
`--action`	What you want to do (be specific — user sees this)
`--reason`	Why you need to do this
`--timeout`	Seconds to wait (default: 60)

Exit Codes

Code	Meaning	Action
`0`	Approved	Proceed with the action
`1`	Denied or timeout	Do NOT proceed, inform user

Important: Prior verbal permission does NOT override the constitution. Always check, even if the user says "you have my permission."

Secure Vault

The vault lets your agent request sensitive data without it being typed in chat or stored in logs.

Vault Types

Type	Description	Fields
`identity`	Personal info	Name, email, phone, address, DOB
`payment`	Credit/debit cards	Card number, expiry, CVV, billing ZIP
`ssn`	Social Security Number	9-digit SSN
`bank_account`	Bank details	Routing number, account number
`otp`	2FA/verification codes	One-time code (ephemeral)
`custom`	Any key-value data	User-defined fields

Requesting Vault Data

# Request identity for shipping form
bash skills/agent-constitution/scripts/request-vault.sh identity "Fill shipping address"

# Request payment for checkout
bash skills/agent-constitution/scripts/request-vault.sh payment "Complete Amazon order"

# Request 2FA code
bash skills/agent-constitution/scripts/request-vault.sh otp "Enter verification code"

How It Works

Agent calls request-vault.sh with type and reason
User gets push notification on iPhone
User selects data and approves with Face ID
Data returns to agent, encrypted end-to-end
Agent reads data, uses it immediately, then deletes
60-second TTL — data auto-expires

Critical: Never store vault data. Never print card numbers, SSNs, or account numbers in chat. Use the data immediately, then discard.

Health Data Sync

Optionally sync Apple Health metrics to your agent for health-aware assistance.

Available Metrics

Weight, body fat percentage
Resting heart rate, HRV, walking heart rate
Sleep hours (deep, REM, light breakdown)
Steps, walking distance, flights climbed
VO2 max, active calories, exercise minutes
Workout history (type, duration, calories)

Syncing Health Data

# Pull new data from relay and regenerate dashboard
bash skills/agent-constitution/scripts/sync-health.sh

# Read latest metrics (no network)
bash skills/agent-constitution/scripts/fetch-health.sh latest

# Get 14-day history
bash skills/agent-constitution/scripts/fetch-health.sh history

Data Storage

Health data is stored locally in your workspace:

personal/health-history/YYYY-MM-DD.json — Daily snapshots
personal/health.md — Auto-generated dashboard

Drift Testing

AI agents can drift — forget rules, misinterpret them, or cave under pressure. Drift testing measures actual compliance.

How It Works

App generates realistic test prompts (probes)
Probes are sent to your agent through the relay
Agent responds naturally — doesn't know it's being tested
Responses are evaluated for rule compliance
Results show in the app's Compliance tab

Running Drift Tests

# Check for pending probes and run tests
bash skills/agent-constitution/scripts/run-drift-test.sh

Safe by Design

All probes use inert targets — @example.com emails, 555 phone numbers, /tmp/ files. Even if the agent executes, nothing harmful happens.

End-to-End Encryption

All sensitive data is protected with AES-256-GCM encryption. The relay can't read your vault data, health metrics, or constitution checks.

How It Works

Algorithm: AES-256-GCM (authenticated encryption)
Key derivation: HKDF-SHA256 from shared master secret
Directional keys: Separate keys for App→Agent and Agent→App
Nonces: Random 12-byte nonce per message
Auth tags: 16-byte GCM tag for integrity verification

Key Exchange

Encryption keys are established during pairing. The master key is stored in iOS Keychain and your agent's secrets file.

File Integrity Protection

Agent Constitution monitors critical files for tampering. If your agent modifies its own rules or scripts, the app detects it.

Protected Files

AGENTS.md — Agent instructions
active-rules.json — Constitution rules
check-constitution.sh — Approval request script
request-vault.sh — Vault request script
Encryption scripts and utilities

How It Works

On each heartbeat, file hashes are computed
Manifest is signed with HMAC-SHA256
App compares against known-good values
If any file changed, tamper alert is shown

API Reference

All communication goes through the relay server via standard HTTP.

Base URL

https://clawd-relay.fly.dev

Authentication

Authorization: Bearer YOUR_CHANNEL_TOKEN

Push Message

POST /channel/{channelId}/push?role=gateway
Content-Type: application/json

{
  "type": "constitution_check",
  "requestId": "unique-id",
  "ruleTitle": "Ask before sending work emails",
  "actionDescription": "Send email to team@company.com",
  "reason": "User requested weekly update"
}

Pull Messages

GET /channel/{channelId}/pull?role=gateway&wait=30

Long-polls for up to 30 seconds. Returns messages or empty array.

Message Types

Type	Direction	Description
`constitution_check`	Agent → App	Request approval
`constitution_response`	App → Agent	Approval decision
`vault_request`	Agent → App	Request sensitive data
`vault_response`	App → Agent	Encrypted vault data
`health_sync`	App → Agent	HealthKit metrics
`constitution_rules_sync`	App → Agent	Updated rules
`drift_probe_message`	App → Agent	Drift test prompt
`drift_probe_response`	Agent → App	Drift test result

Self-Hosting

The relay is open source. Deploy your own:

git clone https://github.com/arunrlverma/agent-constitution.git
cd relay4agents/relay
npm install
npx tsx src/relay-node.ts