The openclaw sub-agent pairing approval prompt blocks unattended automation when sub-agents inherit node tool access they do not need. This article covers why it fires, which of two situations you are in, and the specific config fix for each.
TL;DR
Sub-agents trigger pairing approval prompts when they are spawned with access to node tools (camera, screen, location, notifications) that require device authorization. If your sub-agents do not need device access, restrict their tool permissions in the spawn call to exclude node tools. If they do need device access, pre-authorize the sub-agent’s session using a bootstrap token so approval is granted once and not repeated on every run.
Why the approval prompt appears at all
OpenClaw’s node pairing system connects the gateway to physical devices (Android phones, iPhones, and macOS companions) and exposes their hardware capabilities (camera, microphone, screen, location, notifications) as tools the agent can call. These are powerful capabilities with real privacy implications. The pairing approval prompt is the explicit consent layer: before any session can access a paired device’s capabilities, the device owner must approve that session.
Sub-agents inherit the tool list of their parent session by default. If your main agent session has node tools available, and you spawn a sub-agent, that sub-agent also has node tools in its available tool list. The first time it tries to use one, or in some configurations, the first time it initializes, the pairing system requests approval for that new session. This is correct behavior from a security standpoint. A new session accessing your physical devices for the first time should require your explicit consent. The friction becomes a problem only when it interrupts automations that never needed device access in the first place. The problem is that most sub-agents are spawned for tasks that have nothing to do with device access. For those sub-agents, the openclaw sub-agent pairing approval prompt is entirely preventable with a one-line config change. Running a research task, writing an article, processing queue items: the approval prompt interrupts the automation flow unnecessarily.
I keep getting a device pairing approval prompt when my sub-agents start. Tell me: what tools are currently available to spawned sub-agents in my setup? Are node tools (camera, screen, location, notifications) included in the sub-agent tool list? Read my openclaw.json and identify whether sub-agents inherit node tool access from the main session, and what config change would restrict sub-agents from having node tools unless explicitly granted.
Two distinct situations that look the same
Before changing anything, it is worth distinguishing which of two situations you are in. They require different fixes and conflating them leads to either breaking legitimate device access or repeatedly applying a fix that does not address the actual cause.
Situation A: Sub-agents do not need device access and should never trigger the prompt
This is the most common situation. You are using sub-agents for autonomous tasks (content generation, data processing, web research, queue management) and none of those tasks involve camera, screen, location, or notifications on a paired device. The approval prompt is a false positive caused by sub-agents inheriting node tool access they do not need.
The fix is to explicitly exclude node tools when spawning sub-agents, or to configure the sub-agent policy to not inherit node tools by default. Neither change affects your main agent’s device access.
Situation B: Sub-agents legitimately need device access but the approval is repeating
Some automation workflows genuinely involve device capabilities: a sub-agent that takes a screenshot to verify a result, a cron-spawned agent that reads a notification to decide what to do next, or a sub-agent that uses location to contextualize a task. In these cases, the approval prompt appearing once is expected. The problem is when it appears on every run, meaning the authorization from the previous run is not being persisted.
The fix here is not to remove device access, but to make the authorization persistent using a bootstrap token or a pre-authorized session configuration so the approval is granted once and remembered.
Help me determine which situation I am in. Do my sub-agents actually use any node tools (camera, screen_record, location_get, notifications_list, etc.) during their runs? Check my recent sub-agent session histories and tell me whether any node tool calls appear in them. If no node tool calls appear, I am in Situation A and the prompt is a false positive. If node tool calls do appear, I am in Situation B and need persistent authorization.
Fix for Situation A: Restricting node tools from sub-agents
When spawning sub-agents with sessions_spawn, the tool access the sub-agent receives is determined by a combination of the parent session’s available tools and the sub-agent’s own configuration. The cleanest way to prevent node tool inheritance is to use explicit tool restrictions in the spawn call or to configure a sub-agent profile that excludes node tools.
I want to spawn sub-agents without giving them access to node tools (camera, screen, location, notifications). Show me the sessions_spawn call syntax that restricts tool access for the spawned session. Specifically: is there an allowedTools or excludeTools parameter in sessions_spawn? If not, what is the correct way to spawn a sub-agent with a restricted tool set that excludes all node-related tools?
If sessions_spawn does not expose a direct tool restriction parameter in your OpenClaw version, the alternative is to use a sub-agent profile. A sub-agent profile is more durable than per-spawn parameters anyway: if you update your automation code to spawn sub-agents in a new location, you do not have to remember to add the tool restriction parameter in the new call. It is in the profile and applies automatically. A sub-agent profile is a named configuration in openclaw.json that defines the default tool set, model, and permissions for sub-agents spawned with that profile. By creating a profile that excludes node tools and using it for all automation spawns, you get consistent tool restriction without having to specify it in every spawn call.
Read my openclaw.json and check whether there is an agents.list or agents.profiles section that defines sub-agent configurations. If there is, show me how to create or modify a “automation” profile that excludes node tools. If there is not, tell me what the correct config structure is for defining sub-agent tool restrictions in my OpenClaw version, and what keys to add to my config to create one.
Tool restriction scope
Restricting node tools from sub-agents does not affect your main agent session. Your main agent retains full access to all paired device capabilities. The restriction only applies to sessions spawned after the config change takes effect. Existing running sub-agent sessions are not affected until they are respawned. If you have long-running persistent sub-agent sessions, you may need to restart them for the new tool restrictions to apply.
Fix for Situation B: Persistent authorization for sub-agents that need device access
When a sub-agent legitimately needs to access a paired device, the approval should be granted once and persist for future runs. The mechanism for this in OpenClaw is either a bootstrap token (a pre-authorized credential passed to the sub-agent at spawn time) or a registered sub-agent session that retains its authorization across runs.
I have a sub-agent that legitimately needs access to a paired device (specifically: [camera / screen / location / notifications, specify which]). I want to pre-authorize this sub-agent so it does not prompt for approval on every run. Tell me: does my OpenClaw version support bootstrap tokens for sub-agent sessions? If so, show me how to generate a bootstrap token for this sub-agent and how to pass it in the sessions_spawn call. If bootstrap tokens are not supported, what is the alternative for persistent device authorization?
Bootstrap tokens work by pre-registering a session identity with the node pairing system. The paired device approves the session once, that approval is stored against the session identity, and subsequent spawns that present the same identity do not prompt again. The key requirement: the sub-agent must be spawned with a consistent session identity (a label or session key) rather than generating a new random identity on each spawn. A sub-agent spawned with label: "device-checker" every time retains its authorization. A sub-agent spawned without a label gets a new random identity and triggers a new approval prompt each time.
Check whether my sub-agent spawns for device-access tasks are using consistent session labels or generating new random identities each time. Look at my recent sessions_spawn calls in session history. Do they include a label parameter? If not, update my automation to use a consistent label for each sub-agent that needs device access. Show me what the sessions_spawn call should look like with a label included.
Persistent sessions vs fresh spawns
There is a design decision embedded in the “use consistent label” fix: a sub-agent with a persistent label accumulates session history across runs. If you are spawning it frequently, its context window grows with each run. For short-lived automation tasks, this is manageable. For long-running daily automations, the session history growth can eventually cause compaction or slow response times. The alternative is to use mode: "run" (one-shot) spawns with a consistent label, which creates a fresh session context each time but registers the same identity for pairing authorization purposes. Check which mode your current sub-agent spawns use and whether session history growth is a concern for your use case.
Special case: cron-spawned sub-agents and the approval problem
The approval prompt problem is most disruptive when it hits cron-spawned sub-agents, because a cron job runs unattended and the approval prompt blocks the entire execution until someone responds. A cron job that fires at 3am and waits for a pairing approval that never comes either times out silently or continues to block, depending on your OpenClaw version’s timeout behavior.
I have cron jobs that spawn sub-agents and the pairing approval prompt is blocking them from completing. Tell me: what happens to a cron-spawned sub-agent that triggers a pairing approval prompt and never receives approval? Does it time out, does it hang indefinitely, or does it fail with an error? Check my recent cron run history for any jobs that show signs of this: incomplete runs, long execution times, or no output where output was expected.
For cron-spawned sub-agents, the fix must be applied before the next scheduled run. A cron job that fires before the fix is in place will get stuck again in exactly the same way. The priority order for fixing this situation:
- First, stop the bleeding: If cron jobs are currently hanging, check the openclaw cron scheduler and identify any runs that are stuck waiting for approval. Cancel them if they are blocking subsequent runs in the queue.
- Then apply the correct fix: Either restrict node tools from the sub-agent (Situation A) or pre-authorize with a consistent label (Situation B).
- Then test before the next scheduled run: Manually trigger the cron job and confirm it completes without prompting for approval. Use the openclaw cron management tools to run the job immediately rather than waiting for its scheduled time, then check the run result and execution time. A clean run completes in its normal expected time window and shows a success status. A run that completes in under one second is also suspicious. It may have short-circuited rather than actually running. A run that is still blocked shows as still running or times out.
Check my OpenClaw cron scheduler for any jobs that are currently running, stuck, or showing unusual execution times. For any jobs that spawn sub-agents, tell me whether those sub-agents are configured with node tool restrictions or consistent labels. Flag any jobs that are at risk of the pairing approval blocking problem.
Understanding the approval mechanism so you can configure around it
The approval prompt is generated by the node pairing plugin when a session requests device access for the first time. The plugin checks whether the requesting session has a stored authorization record. If it does, access is granted silently. If it does not, the prompt is sent to the device asking the owner to approve or deny.
Three things control whether the openclaw device pairing prompt fires, and all three must be in the correct state for silent authorization to work. If any one of them is wrong, the prompt fires regardless of the other two.
- Whether the session has node tools in its available tool list: A session with no node tools in its tool list never triggers the pairing check, because it never has the capability to request device access in the first place.
- Whether the session has an existing authorization record: A session that was previously approved has a stored record. The plugin finds it and grants access without prompting.
- Whether the session identity is consistent: Authorization records are keyed to session identity. A new random session identity has no record and triggers a new prompt. A consistent label re-uses the stored record. This is easy to verify: look at two consecutive spawn calls and check whether the label value is hardcoded (consistent) or generated dynamically (inconsistent). A timestamp, a UUID, or a random string in the label means a new identity every time.
Show me the current device pairing authorization records stored in my OpenClaw setup. Tell me which session identities have active authorization records, when each was approved, and which devices (by node name or ID) were involved. This will help me understand which sub-agent sessions are already authorized and which ones are triggering new prompts.
Approval records and session cleanup
If you regularly delete old sessions or run a session cleanup cron, confirm it is not also deleting the authorization records for sessions that need persistent device access. Some OpenClaw versions store authorization records alongside session data, meaning a session cleanup that removes old session entries also removes the authorization record, causing the next run to prompt again. If this is happening on a schedule matching your cleanup cron, that is the root cause. Either exclude device-access sessions from your cleanup policy, or switch to storing authorization records in a separate location that cleanup does not touch.
Exec approvals vs pairing approvals: not the same thing
A common point of confusion: OpenClaw has two separate approval mechanisms that look similar but cover different things. The exec approval prompt fires when the agent tries to run a shell command that requires confirmation. The device pairing approval prompt fires when a session requests access to a paired device’s hardware capabilities. They are configured separately and fixing one does not affect the other.
If you disabled exec approvals (execApprovals.enabled: false) hoping it would also suppress pairing prompts, it did not. Exec approval config and node pairing authorization are independent systems. Pairing prompt suppression requires either removing node tools from the session or pre-authorizing via a persistent session identity. A quick way to verify which system is prompting: exec approval prompts appear inline in your chat interface and typically include a command string to approve or deny. Device pairing prompts appear on the physical device as a push notification. If you are not seeing any notification on your device and the sub-agent is simply stuck or timing out, the device may be offline and not receiving the prompt. That is a device reachability problem, not an authorization configuration problem.
Read my openclaw.json and tell me the current state of both approval systems: the exec approval config (execApprovals section) and the node pairing authorization config (device-pair plugin or similar). Are they configured separately? What is the current setting for each? If exec approvals are disabled but device pairing approvals are still firing, confirm this is expected and that I need to address them via the sub-agent tool restriction or persistent session label approach, not via the exec approval config.
Verifying the fix is working
After applying either the tool restriction fix or the persistent authorization fix, the verification test is the same: spawn a sub-agent and confirm it completes its task without triggering a pairing approval prompt.
Test my sub-agent pairing approval fix. Spawn a sub-agent using the same configuration I use for my automated tasks and have it complete a simple task (such as “list the files in the workspace root and report back”). Watch for any pairing approval prompts during the spawn and execution. Report whether the sub-agent started, ran, and completed without triggering any device authorization prompts. If any prompts appeared, tell me at what point in the execution they fired.
For cron-scheduled tasks, also run a manual trigger of the cron job and confirm it completes end-to-end without hanging. Checking the cron run history after the manual trigger shows whether the run completed with an exit status or whether it is still in a pending state.
FAQ
What exactly triggers the device pairing approval prompt in OpenClaw sub-agents?
The prompt fires when a sub-agent session requests access to a node tool and the pairing plugin does not find an existing authorization record for that session’s identity. This happens in two conditions: the session is new and has never been authorized (no record exists), or the session used a new random identity and the previous record was stored under a different identity. The prompt is sent to the paired device, not to your chat interface. If you are seeing a prompt in your Telegram or Discord chat, that is a different system. The actual device pairing prompt appears as a notification on the paired Android, iOS, or macOS device asking you to approve or deny the connection request.
I approved the pairing once but the prompt keeps coming back. Why?
The most common cause is that each spawn generates a new random session identity. When you approved the prompt, you authorized that specific session identity. The next spawn created a different identity with no record, and the prompt fired again. The fix is consistent session labels as described in the Situation B section. The second most common cause is session cleanup removing the authorization record along with old session data. If you have an automated session cleanup running, check whether it is removing the records associated with your device-access sub-agents. A third cause in some OpenClaw versions is authorization record expiry: records have a TTL and expire after a set period, requiring re-authorization. Ask your agent to check whether authorization records in your setup have an expiry time configured.
Can I permanently pre-approve all sub-agents for device access without prompting?
This depends on your OpenClaw version’s node pairing security model. Some versions support a wildcard approval that grants all sessions from a given main agent access to paired devices without individual prompts. This is a significant security reduction: any sub-agent that is spawned, including ones spawned by automated systems or external triggers, would have device access without your explicit review. Before enabling this, consider whether your main agent handles messages from sources you do not fully control. If it does, a compromised or manipulated session could use device access (camera, screen capture, location) without triggering any prompt. The safer approach is the consistent label method, which pre-authorizes specific named sessions rather than granting blanket access.
My sub-agent cron jobs are timing out waiting for pairing approval. How do I unstick them now?
First, check the cron scheduler for stuck runs: ask your agent to list active cron runs and identify any that have been running longer than expected. Cancel any stuck runs through the cron management interface. Then check whether the cron job’s last run left any state that needs cleanup (a sub-agent session stuck in a waiting state, a lock file, or a partial task result). Once you have cleared the stuck runs, apply the fix from this article before the next scheduled run fires. Do not let the job run again in its current configuration or it will immediately get stuck again. Test with a manual trigger after applying the fix to confirm it completes cleanly before leaving it to run on schedule.
What is the difference between the nodes tool and node pairing? I keep confusing the terminology.
The nodes tool is a single tool that provides a collection of actions: status, camera_snap, screen_record, location_get, notifications_list, and others. It is one tool with many action types. “Node pairing” is the process of connecting a physical device to your OpenClaw instance so the nodes tool can reach it. You pair a device once (by scanning a QR code in the OpenClaw companion app), and after that the nodes tool can use all the capabilities that device exposes. The “device pairing approval prompt” is the authorization request that fires when a new session first tries to use the nodes tool against a paired device. Removing the nodes tool from a sub-agent’s tool list prevents it from ever reaching paired devices at all, which is why it eliminates the prompt entirely for Situation A.
If I restrict node tools from sub-agents, can I still use the nodes tool in my main agent session?
Yes. Tool restrictions on sub-agents are scoped to the spawned session only. Your main agent session retains whatever tools are configured for it in openclaw.json under the agents.defaults or agents.main config. The sub-agent tool restriction is applied at spawn time and only affects that spawned session. Subsequent sub-agents you spawn with the restriction also get it; sub-agents spawned without the restriction inherit normally. Your interactive main agent session is never affected by sub-agent tool config changes.
How do I tell whether the pairing approval prompt I am seeing is from the device pairing system or something else?
Genuine device pairing approval prompts appear as push notifications on your paired device (phone or Mac) with two options: approve or deny. They do not appear in your Telegram, Discord, or other chat interface. If you are seeing an approval message in your chat interface with text like “approve this action” or a /approve command, that is an exec approval prompt, not a device pairing prompt. If you are not seeing any notification at all but your sub-agent is just stuck, the prompt may be going to a device that is offline or has notifications disabled. Ask your agent to check whether your paired device is reachable and has received any pending authorization requests.
Designing sub-agents for unattended operation
The pairing approval problem is a symptom of a broader design issue: sub-agents spawned for unattended automation need to be explicitly designed for autonomy, not simply inherited from an interactive main agent setup. An interactive main agent benefits from broad tool access because you are present to approve or guide any unexpected actions. An unattended sub-agent benefits from narrow, specific tool access because there is no one present to handle anything that goes sideways.
The principle to apply when designing sub-agents for cron jobs or pipeline automation: give the sub-agent exactly the tools it needs to complete its task and nothing more. This is not just about preventing pairing approval prompts. It is also about limiting blast radius if the sub-agent receives a prompt injection from untrusted content in its context, and about reducing the cost of running the sub-agent (fewer tools in the context means slightly shorter system prompts and faster responses). It is also about operational clarity: a sub-agent with ten tools could have done ten different things on any given run. A sub-agent with two tools can only have done two. When debugging a failed automation, a minimal tool list is easier to reason about.
Review my current sub-agent spawn configuration for my automated tasks. For each type of sub-agent I spawn regularly, tell me: what tools are available to it, which of those tools does it actually use in practice (based on recent session history), and which tools are present but never used. Give me a recommended minimal tool list for each sub-agent type that removes unused tools while keeping the ones it needs.
After the minimal tool review, update each spawn call or sub-agent profile to use only the tools on the recommended list. The first run after the update confirms whether any required tools were accidentally excluded. If the sub-agent fails to complete a task it previously handled, the missing tool will be visible in the error or in the session history where the sub-agent tried to call a tool it no longer had access to. A useful pattern for this transition (and one worth following for any sub-agent change, not just tool restriction): keep the full tool list in place for one supervised run, watch what tools actually get called, then trim to only those. This avoids the trial-and-error of guessing what is needed. One supervised run with logging is worth more than three unsupervised runs with debugging. Document the final minimal tool list for each sub-agent type in a comment in your automation config or SOUL.md. When you update OpenClaw or change your automation, that comment is the reference that tells you what the sub-agent actually needs. Without it, the next person to look at the config (including future you) has to re-derive the tool requirements from scratch.
The node pairing security model and why it works this way
Understanding why the approval system exists helps calibrate how aggressively to work around it. The paired device capabilities in OpenClaw are genuinely sensitive. Camera access can capture images of your physical environment. Screen recording can capture passwords, private messages, and financial information. Location access reveals your physical whereabouts. Notification access exposes the content of every alert your phone receives.
OpenClaw’s design decision to require explicit per-session authorization for these capabilities reflects that sensitivity. The trade-off is that legitimate automation needs extra configuration to work smoothly. The alternative design (allow any session to access paired devices without approval) would make automation easier but would also mean any sub-agent spawned from any context, including one spawned in response to a message from an untrusted user, would have camera and screen access by default.
If you are running a multi-user OpenClaw setup where people other than yourself can trigger sub-agent spawns, think carefully before using the consistent-label persistent authorization approach for openclaw sub-agent pairing approval suppression. An authorized session identity is a persistent capability. If a third party can trigger a spawn with that label, they have indirect access to your device’s capabilities. For single-user personal setups, persistent authorization is a reasonable convenience trade-off. The meaningful risk threshold is: if someone other than you can send a message that causes a sub-agent to be spawned with a label that has device authorization, that person has indirect access to your camera, screen, and location. For a fully personal setup where only you interact with the agent, that threshold is never reached.
Given my current setup, evaluate the security implications of using persistent authorization for my device-access sub-agents. Does my main agent receive messages from sources I do not fully trust? Are any of my automations triggered by external inputs (webhooks, messages from other users, data from web scraping) that an attacker could manipulate? Tell me whether persistent authorization is a reasonable choice for my situation or whether I should use the prompt-per-run approach despite the inconvenience.
Diagnosing the authorization chain when something is still not working
After applying one of the fixes above, if the approval prompt continues to appear, the authorization chain has a gap that the fix did not address. The authorization chain has four links, and a break at any link produces the same visible symptom (a prompt fires) even though the cause and fix are different.
The four links in the authorization chain, in the order to check them (each is a necessary condition; all four must pass for silent authorization to work):
- Link 1: Tool presence check. Does the sub-agent session have node tools in its tool list? If yes, the pairing plugin is active for that session. If no, the plugin never fires. Verify by asking your agent to list the tools available to a spawned sub-agent.
- Link 2: Session identity consistency. Is the sub-agent being spawned with a consistent label, or a new random identity each time? Check the spawn call in your automation code or SOUL.md instructions.
- Link 3: OpenClaw sub-agent authorization record persistence. Is the authorization record being stored and retrieved correctly? Ask your agent to check whether the record exists after an approval and whether it is still present before the next run.
- Link 4: Device reachability. Is the paired device online and able to receive the authorization prompt? A prompt sent to an offline device produces the same blocking behavior as a prompt that was never approved. Ask your agent to check whether your paired device is currently reachable via the nodes tool.
The pairing approval prompt is still firing after I applied the fix. Walk me through diagnosing which link in the authorization chain is broken. Check in order: (1) whether the sub-agent has node tools in its tool list after the fix, (2) whether the spawn call includes a consistent label, (3) whether an authorization record exists for that label, and (4) whether my paired device is currently reachable. Tell me which link is broken and what the specific fix is for that link.
Version differences in sub-agent tool inheritance
The way sub-agents inherit tools from their parent session changed between OpenClaw versions. In earlier versions, sub-agents inherited all parent tools by default with no way to restrict them at spawn time. In more recent versions, explicit tool restriction via spawn parameters or profiles is supported. If the tool restriction approach described in this article does not match the available parameters in your sessions_spawn calls, check your OpenClaw version and compare it against the release notes for tool restriction features. Ask your agent to tell you the current OpenClaw version and whether sessions_spawn in that version supports tool restriction parameters.
Queue Commander: $67
Build sub-agent automations that run unattended without getting stuck
The exact session config, tool restriction patterns, and cron setup that keeps autonomous sub-agents running cleanly: no approval prompts, no stuck jobs, no 3am surprises.