@stakeswky/openclaw-permctl

macOS TCC permission error detection, auto-interception, and guided remediation for OpenClaw agents.

What it does

macOS uses TCC (Transparency, Consent, and Control) to gate access to sensitive resources like screen recording, accessibility, camera, etc. These permissions are per-binary — when Node.js gets upgraded via Homebrew, the binary path changes and permissions break silently.

This plugin:

• Detects TCC permission errors in command output (12 error patterns across 6 permission categories)
• Diagnoses current permission states via the permctl.sh skill
• Guides users through fixing permissions with step-by-step instructions (English & Chinese)
• Identifies which terminal/binary needs authorization (detect-host)
• Monitors permission changes over time (watch for cron/heartbeat integration)
• Provides CLI commands, slash commands, and agent tools

Install

openclaw plugins install @stakeswky/openclaw-permctl

Or clone locally:

git clone https://github.com/stakeswky/openclaw-plugin-permctl
# Add to plugins.load.paths in your OpenClaw config

Configuration

All settings are optional. Defaults work out of the box.

{
  plugins: {
    entries: {
      permctl: {
        enabled: true,
        config: {
          autoDetect: true,      // Auto-analyze exec failures for TCC errors
          notifyOnDenied: true,  // Alert on permission status changes
          language: "auto"       // "auto" | "en" | "zh"
        }
      }
    }
  }
}

Agent Tools (opt-in)

Enable in your agent config:

{
  agents: {
    list: [{
      id: "main",
      tools: { allow: ["permctl"] }  // enables all permctl tools
    }]
  }
}

| Tool | Description | |------|-------------| | tcc_detect | Analyze command output for TCC errors | | permctl_status | Check current permission states | | permctl_guide | Get step-by-step fix instructions | | permctl_detect_host | Identify terminal app and binary paths | | permctl_watch | Check for permission changes since last run |

CLI Commands

openclaw permctl status                    # Check all permissions
openclaw permctl status accessibility      # Check specific permission
openclaw permctl guide screen-recording    # Get fix instructions
openclaw permctl guide accessibility --lang zh  # Chinese instructions
openclaw permctl detect-host               # Show terminal & binary info
openclaw permctl watch                     # Check for changes

Slash Commands

In any chat channel (Telegram, Discord, etc.):

/permctl                          # Check all permissions
/permctl status accessibility     # Check specific permission
/permctl guide screen-recording   # Get fix instructions
/permctl detect-host              # Show terminal info
/permctl watch                    # Check for changes

Permissions Covered

| Permission | TCC Service | Detection Method | |---|---|---| | Accessibility | kTCCServiceAccessibility | osascript probe | | Automation | kTCCServiceAppleEvents | osascript probe | | Screen Recording | kTCCServiceScreenCapture | screencapture test / peekaboo / TCC.db | | Full Disk Access | kTCCServiceSystemPolicyAllFiles | ~/Library/Mail access test | | Camera | kTCCServiceCamera | peekaboo | | Microphone | kTCCServiceMicrophone | peekaboo |

Watch Mode (Cron Integration)

The watch command compares current permission states against ~/.permctl_state.json. Use it with OpenClaw cron for periodic monitoring:

// Example: check permissions every 6 hours
{
  schedule: { kind: "cron", expr: "0 */6 * * *" },
  payload: { kind: "agentTurn", message: "Run permctl_watch and alert me if any permissions changed." }
}

Development

npm install
npm test

License

MIT