Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/nearai/ironclaw/llms.txt

Use this file to discover all available pages before exploring further.

​
ironclaw pairing

Manage pairing requests for direct message channels like Telegram and Slack. When someone sends a DM to your agent from an unknown sender, a pairing request is created that must be approved before the agent will respond.

​
Subcommands

  • list - List pending pairing requests
  • approve - Approve a pairing request by code

​
ironclaw pairing list

List all pending pairing requests for a specific channel.

​
Syntax

ironclaw pairing list <CHANNEL> [FLAGS]

​
Arguments

<CHANNEL> Channel name (e.g., telegram, slack, discord).

​
Flags

--json Output as JSON instead of human-readable format.

​
Examples

# List Telegram pairing requests
ironclaw pairing list telegram

# List Slack pairing requests
ironclaw pairing list slack

# Get JSON output
ironclaw pairing list telegram --json

​
Output

Human-readable format: 
Pairing requests (3):
  ABC12345  user123  username=alice, first_name=Alice  2024-01-15 14:23:45
  DEF67890  user456  username=bob                      2024-01-15 15:30:12
  GHI11121  user789  first_name=Charlie                2024-01-15 16:15:33
Columns:
  • Code - Pairing code to use with approve
  • ID - Channel-specific user ID
  • Metadata - Additional information (username, name, etc.)
  • Created - Timestamp when request was created
No pending requests: 
No pending telegram pairing requests.
JSON format: 
[
  {
    "code": "ABC12345",
    "id": "user123",
    "channel": "telegram",
    "created_at": "2024-01-15T14:23:45Z",
    "meta": {
      "username": "alice",
      "first_name": "Alice"
    }
  },
  {
    "code": "DEF67890",
    "id": "user456",
    "channel": "telegram",
    "created_at": "2024-01-15T15:30:12Z",
    "meta": {
      "username": "bob"
    }
  }
]

​
ironclaw pairing approve

Approve a pairing request using its code.

​
Syntax

ironclaw pairing approve <CHANNEL> <CODE>

​
Arguments

<CHANNEL> Channel name (e.g., telegram, slack). <CODE> Pairing code from the list output (e.g., ABC12345).

​
Examples

# Approve Telegram pairing request
ironclaw pairing approve telegram ABC12345

# Approve Slack pairing request
ironclaw pairing approve slack XYZ99999

​
Output

Success: 
Approved telegram sender user123.
Code not found: 
Error: No pending pairing request found for code: ABC12345
Rate limited: 
Error: Too many failed approve attempts. Wait a few minutes before trying again.

​
How Pairing Works

​
1. Unknown Sender Messages You

When someone sends a DM to your agent from a channel you’ve configured: 
Unknown Telegram user @alice sends: "Hello!"

​
2. Pairing Request Created

The agent creates a pairing request and responds with a code: 
Your pairing code is: ABC12345

Ask the agent owner to approve with:
  ironclaw pairing approve telegram ABC12345

​
3. You Approve the Request

ironclaw pairing list telegram
# Shows: ABC12345  user123  username=alice ...

ironclaw pairing approve telegram ABC12345
# Approved telegram sender user123.

​
4. Sender Can Now Chat

The sender’s next message will be processed normally: 
Alice: "Hello!"
Agent: "Hi Alice! How can I help you today?"

​
Pairing Request Lifecycle

​
Creation

  • Created when an unknown sender messages the agent
  • Includes metadata: username, display name, etc.
  • Generates an 8-character alphanumeric code
  • Valid indefinitely until approved or sender is blocked

​
Approval

  • Marks the sender as trusted
  • Removes the pending request
  • Future messages from this sender are processed normally

​
Re-requesting

If the same sender messages again before approval:
  • Extends the existing request timestamp
  • Returns the same pairing code
  • Does not create a duplicate request

​
Security Features

​
Rate Limiting

Approval attempts are rate-limited to prevent brute-force attacks:
  • Too many failed attempts trigger a cooldown period
  • Cooldown is user-specific (per your IronClaw instance)

​
Code Format

Pairing codes are:
  • 8 characters long
  • Alphanumeric (A-Z, 0-9)
  • Case-insensitive
  • Cryptographically random

​
Automatic Cleanup

Old pairing requests are automatically cleaned up after:
  • 30 days of inactivity (configurable)
  • Approval
  • Manual deletion

​
Storage Location

Pairing data is stored in: 
~/.ironclaw/pairing/<channel>.json
Example: ~/.ironclaw/pairing/telegram.json

​
File Format

{
  "pending": [
    {
      "id": "user123",
      "code": "ABC12345",
      "created_at": "2024-01-15T14:23:45Z",
      "meta": {
        "username": "alice",
        "first_name": "Alice"
      }
    }
  ],
  "approved": [
    "user456",
    "user789"
  ],
  "blocked": []
}

​
Common Workflows

​
Daily Pairing Check

# Check for new pairing requests
ironclaw pairing list telegram

# Approve trusted users
ironclaw pairing approve telegram ABC12345

​
Bulk Approval

# Get JSON list
ironclaw pairing list telegram --json > requests.json

# Review and approve
cat requests.json | jq -r '.[] | .code' | while read code; do
  ironclaw pairing approve telegram $code
done

​
Monitoring Script

#!/bin/bash
# check-pairings.sh - Monitor for new pairing requests

CHANNELS=("telegram" "slack")

for channel in "${CHANNELS[@]}"; do
  count=$(ironclaw pairing list $channel --json | jq 'length')
  if [ $count -gt 0 ]; then
    echo "$count pending $channel pairing request(s)"
    ironclaw pairing list $channel
  fi
done

​
Channel-Specific Metadata

​
Telegram

{
  "username": "alice",
  "first_name": "Alice",
  "last_name": "Smith"
}

​
Slack

{
  "user_name": "alice",
  "real_name": "Alice Smith",
  "team_id": "T123456"
}

​
Discord

{
  "username": "alice#1234",
  "discriminator": "1234",
  "global_name": "Alice"
}

​
Troubleshooting

​
”No pending pairing requests”

Either:
  • No one has messaged your agent from unknown accounts, or
  • All requests have been approved/expired
Test by messaging your agent from a new account.

​
”Pairing file not found”

The channel may not be configured: 
ironclaw doctor
Check your .env file for channel configuration.

​
”Code not found”

Possible causes:
  • Typo in the code (codes are case-insensitive)
  • Request already approved
  • Request expired or manually deleted
List current requests: 
ironclaw pairing list <channel>

​
“Rate limited”

Too many failed approval attempts. Wait a few minutes and try again.

​
Manual Pairing File Management

You can manually edit pairing files if needed: 
# View pairing file
cat ~/.ironclaw/pairing/telegram.json

# Edit with your editor
vim ~/.ironclaw/pairing/telegram.json

# Validate JSON
jq . ~/.ironclaw/pairing/telegram.json
Warning: Manual edits can break pairing functionality. Use the CLI commands when possible.

​
Privacy Considerations

  • Pairing requests include user metadata (usernames, names)
  • This data is stored locally in plaintext
  • Consider the sensitivity of stored metadata
  • Regularly clean up old pairing data

Build docs developers (and LLMs) love

Get started for freeTalk to us