mainctrl — Agent Tool Access Control#

mainctrl lets you control which agents can use destructive tools (write, edit, exec, process, apply_patch). Turn it on — main delegates everything to sub-agents. Turn it off — main is free. Add or remove agents from the controlled list to extend protection. Install or remove the companion plugin in one command. No restarts, no config edits.

Invocation Model#

mainctrl is a management/admin skill — it is NOT loaded into your system prompt. The frontmatter settings enforce this:

• disable-model-invocation: true — This skill is excluded from the agent's available skills list at load time. You will never see these instructions unless the user invokes mainctrl explicitly.

• user-invocable: true — The skill is available as the /mainctrl slash command for manual invocation.

When to follow these instructions: Only when the user has explicitly invoked mainctrl via /mainctrl. In all other contexts, this skill is inactive — do not pre-emptively apply its rules or behavior.

Startup Behavior#

Every time mainctrl is loaded (the agent reads this SKILL.md), it MUST:

1. Run ./scripts/mainctrl.sh status to read the current runtime state.
2. Remember the output internally — which tools are blocked, which agents are controlled, and the current exec allow-except config. This contextual awareness guides every subsequent tool call: know when to delegate and which commands can pass through.

Quick Start#

1. Install the plugin and restart: bash

   ./scripts/mainctrl.sh plugin install
   
   

   Then restart the OpenClaw gateway. Safety starts OFF — nothing is blocked yet.

   After restart, run ./scripts/mainctrl.sh status to load the current control state into context per Startup Behavior.

2. Before turning on, verify at least one sub-agent exists and main can spawn it. Check with the agents_list tool — you need at least one agent besides main: text

   agents_list
   
   

   Also verify main's spawn permissions: text

   gateway config.get agents.list → main.subagents.allowAgents
   
   

   mainctrl blocks main's destructive tools and requires at least one sub-agent to delegate the work to. If none is configured or main can't spawn them, set up a sub-agent first.

3. Turn blocking on: bash

   ./scripts/mainctrl.sh on
   
   

4. Verify: bash

   ./scripts/mainctrl.sh status
   
   

   Should show safety: ON and all tools BLOCKED.

5. Emergency off — temporarily allow all tools. When mainctrl is ON, main can't run commands itself. To turn it off:

   • Delegate to a sub-agent (e.g. coder): Spawn a sub-agent to run ./scripts/mainctrl.sh off.

   • Run the script manually if no sub-agent has exec access: bash

     ./scripts/mainctrl.sh off
     
     

Plugin + Skill#

mainctrl is two parts that must be installed together:

• Plugin ( plugin/index.js) — a before_tool_call hook. It reads state.json on every tool call and blocks or allows based on your settings. Installed via ./scripts/mainctrl.sh plugin install.
• Skill (this directory) — the management side. The CLI script ( mainctrl.sh) writes config to state.json; this SKILL.md tells the agent how to behave when blocked.

Both talk through a shared file — the skill writes state.json, the plugin reads it. No sockets, no RPC, no restart.

The skill installs the plugin for you — run ./scripts/mainctrl.sh plugin install to set up both halves in one step.

How it works#

Mainctrl gives the agent two modes, like vi's V and I:

Visual mode ( mainctrl on) — the agent can inspect, search, and read, but cannot modify anything. Every destructive tool call is blocked:

ToolWhy blockedwriteFile creation / overwriteeditIn-place file editsexecShell command executionprocessBackground process managementapply_patchMulti-file patching

Tools NOT blocked#

When mainctrl is ON, these tools remain fully available to the controlled agent:

ToolPurposereadFile reading / inspectionweb_searchWeb searchweb_fetchURL content fetchingsessions_spawnSub-agent delegationsessions_sendCross-session messagingsessions_listSession discoverysessions_historySession historyimageImage analysispdfPDF analysismemory_searchMemory searchmemory_getMemory readmessageChannel messaginggatewayConfig read / statusskill_workshopSkill managementcronJob schedulingnodesNode device queriesttsText-to-speechagents_listAgent discovery

🔴 Do NOT default to exec for inspection tasks. When you need to explore directories, read files, check config, or verify state, use read — it's available, immediate, and never blocked. exec is only for tasks that truly require shell access (build, install, git, etc.), and those should always be delegated to sub-agents.

This is how today's incident happened: the agent used exec for find and ls instead of read — needless blocking and unnecessary sub-agent overhead.

Insert mode ( mainctrl off) — the agent can write files, run commands, and make changes freely.

Switch between them with ./scripts/mainctrl.sh on and ./scripts/mainctrl.sh off.

A lightweight OpenClaw plugin ( extensions/mainctrl) hooks before_tool_call and inspects every tool call. When the caller is one of the controlledAgents and mainctrl is enabled, the above tools are rejected with a delegation message.

Agents not in controlledAgents are never affected — they always have full tool access.

Agent behavior rule#

When the main agent receives the block message:

Delegate this work to a sub-agent instead. Use sessions_spawn to dispatch to coder, tester, auditor, or publicist.

it MUST:

1. Briefly inform the user that the operation has been blocked and is being delegated.
2. Immediately spawn a sub-agent (coder, tester, auditor, or publicist) to complete the blocked operation.

Do NOT wait for the user to confirm — report and delegate in the same turn.

Blocked tool response#

When a controlled agent calls a blocked tool, it receives:

Delegate this work to a sub-agent instead. Use sessions_spawn to dispatch to coder, tester, auditor, or publicist.

The agent follows the Agent behavior rule and spawns a sub-agent to complete the work automatically.

Security Design Notes#

1. Internal guard, not anti-hacker#

This is an internal self-discipline mechanism, not a defense against external attacks. mainctrl makes the LLM agent think twice before proceeding with destructive operations. It is not a sandbox or security boundary; the goal is to prevent accidental misuse by the agent itself (e.g., main writing code when it should delegate to coder), not to stop a malicious attacker. Treat it as a guardrail that makes the LLM say "should I really do this myself?" — not a fortress.

2. Explicit delegation#

When spawning a sub-agent to replace a blocked operation, always state who is being delegated and why. For example:

exec blocked. Delegating to coder to run the command.

This transparency helps the user understand the delegation chain at a glance.

3. Direct for skill execution#

All CLI commands in this skill are designed for programmatic execution (by agents or other skills). There are no interactive prompts, confirmations, or friction — they complete in one shot. This is intentional: when an agent needs to toggle safety or reconfigure, it must not hang waiting for user input.

Why this approach#

mainctrl uses an OpenClaw before_tool_call plugin hook rather than agent-level tools.deny for two reasons. First, tools.deny is static — toggling it requires editing agent config and restarting the gateway. The plugin hook reads state.json on every call, so safety can be toggled at runtime with a single command and takes effect immediately. Second, agent configs cannot distinguish which caller is invoking a tool; the plugin hook can selectively block agents listed in controlledAgents while leaving sub-agents (like coder) unaffected.

Exec allow-except — safe exec commands#

execAllowExcept only takes effect when exec is in blockedTools. If exec is not blocked, all commands pass through regardless of this config.

When exec is in the blocked tools list, mainctrl inspects the command before blocking. Commands listed as keys in execAllowExcept are allowed through — unless the command line contains an allow-except pattern.

How it works#

1. Command's first word is looked up in execAllowExcept
2. If the command is not a key → blocked as usual (delegate)
3. If the command is a key → each allow-except pattern is checked against the full command string
4. If any allow-except pattern matches → blocked with a specific reason
5. If no allow-except pattern matches → allowed

Allow-except patterns#

CommandAllow-except patternsWhat they catchfind``-exec, -okExecute commands on matched files-deleteDelete matched files-fprintWrite to arbitrary files|, $( , > , >>Pipes, command substitution, redirectionls``> , >> , ``pwd``> , >> , ``sed``> , >> , ``.java , .py , .js , .html , .cssDirect source file modificationcat``> , >> , ``

Substring matching is used (e.g. -exec also catches -execdir).

Configuration#

execAllowExcept lives in state.json. To modify it, edit the file directly (no CLI subcommand for this):

bash

# Set via CLI
./scripts/mainctrl.sh allow-except '{"find":["-exec","-ok","-delete","-fprint","|","$(",">",">>"],"ls":[">",">>","|"],"pwd":[">",">>","|"],"sed":[">",">>","|",".java",".py",".js",".html",".css"],"cat":[">",">>","|"]}'

Run ./scripts/mainctrl.sh status to see the current allow-except configuration.

Examples#

text

ls ~/                    # ✅ allowed (no allow-except hit)
find . -type f            # ✅ allowed
find . -exec rm {} \;     # 🛡 blocked: "-exec"
ls > /tmp/foo             # 🛡 blocked: ">"
sed -i 's/foo/bar/g' file.java  # 🛡 blocked: ".java"
cat /etc/hosts            # ✅ allowed (no allow-except hit)
rm -rf /                  # 🛡 blocked: not in allow-except map

Commands#

Use the mainctrl.sh script in the scripts/ directory:

CommandEffect./scripts/mainctrl.sh statusShow current state (enabled + agents + per-tool + exec allow-except)./scripts/mainctrl.sh onEnable blocking./scripts/mainctrl.sh offDisable blocking (all tools pass through)./scripts/mainctrl.sh agents '<json-array>'Set which agents are controlled./scripts/mainctrl.sh tools '<json-array>'Set or show blocked tools list./scripts/mainctrl.sh allow-except '<json>'Set execAllowExcept config (JSON object)./scripts/mainctrl.sh refresh-memoryWrite current status to ~/.openclaw/workspace/MEMORY.md./scripts/mainctrl.sh plugin installInstall the companion plugin via openclaw plugins./scripts/mainctrl.sh plugin removeDisable and uninstall the companion plugin

Plugin Installation#

Instead of manually adding the plugin path to plugins.load.paths, use the built-in script:

bash

# Install the plugin
./scripts/mainctrl.sh plugin install

# Remove the plugin
./scripts/mainctrl.sh plugin remove

This calls openclaw plugins install / uninstall, which manages the plugin under OpenClaw's native plugin registry. After install or remove, restart the gateway for the change to take effect.

controlledAgents config#

controlledAgents lists which agents are subject to tool blocking. Example configs:

json

{ "enabled": true, "controlledAgents": ["main"] }

json

{ "enabled": true, "controlledAgents": ["main", "auditor"] }

State file#

skills/mainctrl/scripts/state.json (in the scripts/ directory):

json

{
  "enabled": false,
  "controlledAgents": ["main"],
  "blockedTools": ["write", "edit", "exec", "process", "apply_patch"],
  "execAllowExcept": {
    "find": ["-exec", "-ok", "-delete", "-fprint", "|", "$(", ">", ">>"],
    "ls":   [">", ">>", "|"],
    "pwd":  [">", ">>", "|"],
    "sed":  [">", ">>", "|", ".java", ".py", ".js", ".html", ".css"],
    "cat":  [">", ">>", "|"]
  }
}

Changes take effect immediately on the next tool call — no restart needed.

Plugin#

The companion extension lives at extensions/mainctrl/. It reads state.json on every before_tool_call event, so the latency is a single fs.readFileSync per tool call.

Troubleshooting#

SymptomCheckBlocking not working./scripts/mainctrl.sh status — ensure safety is ONPlugin not loadedopenclaw plugins list — ensure mainctrl is enabledAgent still blocked after offRestart the gatewaySub-agent blocked tooRun ./scripts/mainctrl.sh agents main to restrict to main onlySafe exec command blockedCheck ./scripts/mainctrl.sh status — command must be in exec allow-except map and not matching allow-except patterns

Examples#

What you can do with mainctrl:

Control the safety switch#

bash

./scripts/mainctrl.sh on      # Block destructive tools — delegate mode
./scripts/mainctrl.sh off     # Allow all tools — free mode
./scripts/mainctrl.sh status  # Check current state

Add or remove controlled agents#

bash

./scripts/mainctrl.sh agents '["main"]'             # Control main only
./scripts/mainctrl.sh agents '["main","auditor"]'   # Add auditor to the list
./scripts/mainctrl.sh agents '[]'                   # Clear all (falls back to default)

Add or remove blocked tools#

bash

./scripts/mainctrl.sh tools                                          # Show which tools are blocked
./scripts/mainctrl.sh tools '["write","exec"]'                       # Block only write and exec
./scripts/mainctrl.sh tools '["write","edit","exec"]'                # Block three
./scripts/mainctrl.sh tools '["write","edit","exec","process","apply_patch"]'  # Block all five (default)
./scripts/mainctrl.sh tools '[]'                                     # No tools blocked

Manage the plugin#

bash

./scripts/mainctrl.sh plugin install   # Install the companion plugin
./scripts/mainctrl.sh plugin remove    # Uninstall the plugin

Set exec allow-except#

bash

./scripts/mainctrl.sh allow-except '{"find":["-exec","-ok","-delete","-fprint","|","$(",">",">>"],"ls":[">",">>","|"],"pwd":[">",">>","|"],"sed":[">",">>","|",".java",".py",".js",".html",".css"],"cat":[">",">>","|"]}'
./scripts/mainctrl.sh allow-except '{}'              # No exec exceptions, all exec blocked

Verification#

• Plugin installed: ./scripts/mainctrl.sh plugin install
• Blocking active: ./scripts/mainctrl.sh status shows safety ON
• Tool blocked: main agent exec/write/edit/process/apply_patch return block message
• Sub-agent unaffected: coder can still use write/exec
• Toggle works: ./scripts/mainctrl.sh off then ./scripts/mainctrl.sh on restores blocking
• Exec allow-except works: ls ~/ passes, ls > /tmp/foo blocked