OpenScopescoped, not open-ended
Try the demoDownload OpenScope

OpenClaw User Guide

This guide is for a typical OpenClaw user who wants to let the agent access important local macOS apps in a controlled way.

The short version:

  • OpenClaw should not automate Notes, Calendar, or similar apps directly
  • OpenClaw should call openscope
  • OpenScope decides whether the request is allowed
  • every decision is logged
  • OpenClaw should only be configured with low-permission agent labels

That gives you a safer setup than letting the agent talk to local apps however it wants.

What OpenScope Does

OpenScope is a local broker between OpenClaw and sensitive apps.

Instead of:

OpenClaw -> Apple Notes directly

you use:

OpenClaw -> openscope -> openscoped -> protected local app

This adds four protections:

  1. OpenClaw uses a named agent identity such as openclaw
  2. You choose exactly which actions that agent may perform
  3. Requests are audited in ~/.openscope/audit.jsonl
  4. macOS Automation approval is attached to OpenScope's signed broker

For local setups, the agent name is best understood as a policy label, not as a secret API key.

What Works Today

Today, OpenScope includes bundled protected access to Apple Notes and Apple Mail. It also bundles common passthrough apps such as Calendar, Reminders, Contacts, Safari, and Messages.

That means a novice user can use OpenScope right now to secure OpenClaw's access to both apps out of the box.

Those passthrough apps are intentionally denied by default. The user can opt in with one privileged activation command instead of falling back to raw osascript.

Install And Provision OpenScope

Before OpenClaw can use OpenScope, OpenScope must be installed on the Mac.

Where To Get It

Download the latest installer package from the project's latest GitHub release:

cylonix/openscope latest release

Open the release page and download the packaged .pkg asset for your version.

You can also browse all releases here:

cylonix/openscope releases

Install It

Open OpenScope.pkg and complete the installer.

The installer is expected to:

  • copy OpenScope.app into /Applications
  • install the openscope CLI
  • register and start the openscoped background service
  • create the initial ~/.openscope/ configuration directory

Verify The Install

After installation, open Terminal and run:

openscope status
openscope doctor

You want openscope status to show that the daemon is running.

Provision OpenClaw

Once OpenScope is installed, the installer pre-registers openclaw as the default low-permission label for OpenClaw.

By default, that label can:

  • list notes inside a folder you name explicitly
  • read notes inside a folder you name explicitly
  • not enumerate all folders with list_folders
  • not access folders whose names contain protected keywords such as private or hidden
  • list messages only in Inbox
  • read messages only in Inbox
  • not read attachments through the bundled Mail app

The important practical rule is:

  • only register and configure labels that you want OpenClaw to use
  • do not create a broader-permission OpenClaw label unless you truly need it
  • do not reuse a manual or admin label for OpenClaw

If you want to customize access beyond the default:

sudo openscope policy allow --agent openclaw --app notes --action list_notes --folder Work
sudo openscope policy allow --agent openclaw --app notes --action read_note --folder Work
sudo openscope app activate --agent openclaw calendar reminders
openscope notes blacklist list
sudo openscope notes blacklist add finance
openscope mail domains list
sudo openscope mail domains add mycompany.com

This is much better than giving the agent broad unrestricted access.

For most users, the safest pattern is to have one OpenClaw label with narrow permissions and no separate high-permission OpenClaw label at all.

What OpenClaw May Do During Setup

OpenClaw may help the user walk through installation and provisioning, but it should not silently install packages or widen local app permissions without explicit user approval.

Good setup behavior:

  • tell the user where to download OpenScope
  • ask before running install or policy commands
  • verify setup with openscope status and openscope doctor

Risky setup behavior:

  • downloading and installing OpenScope without clear user consent
  • registering broader-permission labels than the user asked for
  • configuring Notes or future apps with wider policy than necessary

First-Time Automation Approval

The first time OpenScope accesses Notes or Mail, macOS may show an Automation prompt. Approve it for OpenScope.

How OpenClaw Should Use OpenScope

OpenClaw should use commands like these:

openscope notes list_notes --agent openclaw --folder "Work"
openscope notes read_note --agent openclaw --folder "Work" --note "Sprint Plan" --body-only
openscope mail list_messages --agent openclaw --mailbox "Inbox" --limit 20 --unread true
openscope mail read_message --agent openclaw --mailbox "Inbox" --id "<message-id>" --body-only

The best novice pattern is:

  1. Tell OpenClaw the folder name directly instead of giving it folder discovery.
  2. Let it list notes only inside that folder.
  3. Let it read only the note it needs.
  4. Prefer --body-only when OpenClaw only needs text.

How To Think About Notes, Calendar, And Similar Apps

Use this rule of thumb:

  • if the app holds sensitive personal or business data, put it behind OpenScope
  • if OpenClaw needs access, give it a dedicated agent ID
  • start with read-only, narrow permissions
  • widen policy only when you have a real use case

For Notes and Mail, this is already available through the bundled app definitions and the default openclaw agent.

For Calendar, Reminders, Contacts, Safari, Messages, and similar apps, the next step is usually to activate the bundled passthrough app for openclaw:

sudo openscope app activate --agent openclaw calendar

Common Safe Policy Shapes

Safer

  • do not allow list_folders
  • allow list_notes only for Work
  • allow read_note only for Work
  • keep Mail scoped to Inbox
  • add sender-domain restrictions when you want Mail access narrowed further
  • name sensitive folders with a protected keyword such as Private or Hidden
  • provision OpenClaw with only one low-permission label such as openclaw

Riskier

  • allow all folders
  • reuse a broad or legacy agent label for a production OpenClaw deployment
  • let OpenClaw use raw AppleScript outside OpenScope
  • create an admin-style label and also give OpenClaw access to it

Operational Tips

  • Use one agent ID per tool or product integration
  • Keep personal and business folders separated if possible
  • Review ~/.openscope/audit.jsonl occasionally
  • Use openscope policy show --agent openclaw to inspect active rules

Troubleshooting

If OpenClaw says it cannot access a protected app:

openscope status
openscope doctor
openscope policy show --agent openclaw

If access is denied, that usually means the security policy is working as intended. Add a new allow rule only if you want that behavior.

If you are configuring OpenClaw, tell it:

  • use openscope for protected local app access
  • always pass --agent openclaw
  • never bypass OpenScope with direct automation
  • if policy denies a request, ask for permission instead of working around it
  • never use any agent label other than the one explicitly provisioned for OpenClaw

Enterprise Security Model

For enterprise deployments, treat local self-registration as a convenience for development and small self-managed setups, not as the long-term control plane.

The recommended enterprise model is:

  • agent registration is centrally administered
  • policy is centrally approved
  • managed identities and policy are pushed to devices
  • local applications such as OpenClaw do not create or register their own labels

In other words, enterprise customers should not rely on ad hoc local registration for important access control decisions. The local device should enforce identities and policies that were authorized elsewhere.

View raw markdown ↗← All docs