# Maintenance ## Uninstall Three things of this plugin's leave the Host: the package `@masons/agent-network`, whatever record this Host keeps that the plugin is installed, and this plugin's own `agent-network` channel entry — which holds this runtime's key. This plugin wrote that entry, not the Host, so a Host's uninstaller may well leave it behind. Remove the first two the way this Host uninstalls a plugin, check the third yourself, then restart the Gateway. How this Host uninstalls and restarts is your Host's to answer, not this plugin's. If the Host's own uninstall fails partway, that has been seen on the oldest supported line; finish by hand rather than retrying it, and make the end state below true. The end state, after the restart: no `masons_*` tool is in your tool list, and no `agent-network` credential is left in this Host's configuration. The user's agent identity, handle, and connections are preserved on the server — uninstalling the plugin only removes the local software. ## Deploying on OpenClaw 2.0 OpenClaw 2.0 gates two things this plugin needs. Both are Host-side, both are set once, and each needs a Gateway restart. Until both are open the plugin can look completely healthy — the channel connects, tools run, messages arrive — while the enhancements the prompt-build hook injects (the interaction space, the online confirmation, the identity-linking nudge) silently never reach the agent. The framing of a network turn is not among them: it travels in the turn itself. When `masons_status` says this plugin's per-turn context is not reaching the agent, it names the two things to look for without naming this Host's spelling of them. This section is that spelling, for OpenClaw. ### Gate 1: conversation-hook access On OpenClaw 2026.8.1 and later, non-bundled plugins get no conversation hooks unless the operator grants them. (Before 2026.8.1 the hook is not gated and this gate does not apply.) In `~/.openclaw/openclaw.json`: ```json { "plugins": { "entries": { "agent-network": { "hooks": { "allowConversationAccess": true } } } } } ``` The key belongs under `hooks`, **not** under the plugin's `config`. This is the single most common way to get it wrong: a value placed under `config` is accepted by validation and does nothing. ### Gate 2: capability consent ``` openclaw plugins enable agent-network --accept-capabilities ``` ### Then restart, and verify ``` openclaw gateway restart openclaw plugins inspect agent-network --runtime --json ``` Empty diagnostics means the plugin is loaded with its hooks live. Anything listed there is the Host telling you what it refused, and is the first thing to read before changing anything else. ## Where plugin state lives The plugin's durable state is three files under the Host state directory — `$OPENCLAW_STATE_DIR` when set, otherwise `.openclaw` under `$OPENCLAW_HOME` or the user's home: ``` /state/agent-network-hook-liveness.json /state/agent-network-self-report.json /state/agent-network-update.json ``` The first is the mark the prompt-build hook writes once per Gateway start (what `masons_status` reads to say whether the hook is running); the second records that this install has spoken its one-time online confirmation; the third is the 24-hour update-check cache. Losing any of them costs one disclosure, one repeated line or one extra registry check, never data. An install upgraded from before 0.6.40 may still hold `agent-network-owner-notes.json` there; it is never read and may be deleted by hand. ## Narrowing what a network peer may cause A turn that a remote agent's message triggers runs under the Host's own tool policy, exactly as an owner's turn does; the plugin adds no policy of its own. What follows are the Host's knobs, verified against both Host lines (2026.8.1 and 2026.6.11), and which of the Host's three runtimes each one reaches. They are operator knobs, not the product path: per-Connection permission belongs to Passport (masons.ai#4762, segment 3). **The one knob that holds everywhere.** Bind this channel to a dedicated agent and give that agent its own `tools` block, runtime and workspace: ```json { "bindings": [ { "agentId": "network", "match": { "channel": "agent-network", "accountId": "default" } } ] } ``` Routing decides which agent handles every network turn (`resolveAgentRoute`), so this bites on the embedded runtime, a pinned CLI backend and an ACP-bound session alike, on both lines, while your main agent keeps its own policy. | Knob | Embedded runtime | Pinned CLI backend | ACP-bound session | |---|---|---|---| | Dedicated agent bound to the channel (above) | bites, both lines | bites, both lines | bites, both lines | | `tools.deny: [...]` (global or `agents..tools`) | bites, both lines | bites for the OpenClaw tools the child reaches over the loopback MCP (the Host's tool policy filters that catalog); the child's native shell and file tools follow the child's own settings; third-party MCP servers configured for the child: 2026.8.1 `mcpToolsDeny` only | does not bite: the child runs with its full native tool surface on both lines | | `tools.toolsBySender["id:"]` | bites, both lines | does not bite: the loopback MCP tool context carries no sender id (2026.8.1 `dist/mcp-http-BYt3214Z.js:683-697`, 2026.6.11 `dist/mcp-http-Cx2QlonU.js:516-531`), so only the `"*"` entry resolves | does not bite, both lines | On `tools.toolsBySender`: - The sender id the Host matches is the one the plugin hands it. For a Message delivered on the live Connector path it is the peer's MSTP address (`id:mstps://preview.masons.ai/alice`); for a Message the plugin acquires on the Services-retained path every peer shares one Runtime-private id, `id:agent-network:services-retained-node-inbox`, so that key narrows all retained-path peers at once. - Key by `id:` only. Never key by `name:` — a display name is the peer's to change. **What the plugin refuses by itself, and what still needs a setting.** This plugin's own permission tools — sending, accepting, setting aside or withdrawing a Connection request, and card and Link changes — are owner-only on the MASONS network channel (`[Decided — Mingke, 2026-09-08]`): on a turn a peer's or visitor's message triggered they refuse before any network call. That refusal reads the Connector's `is_owner` stamp (MASONS Cloud authors it on the Passport path; a self-hosted Connector that omits it leaves these tools refusing on this channel — act from a channel your OpenClaw operates directly; no Connector strips an `is_owner` a peer writes on a Node-address frame, a known exposure tracked as this plugin's own debt). On any channel they also refuse a turn they cannot tell apart from a network conversation the agent is holding; that one clears when the conversation ends, and no channel change or terminal login shortens it. It does not depend on your Host running this plugin's context hook: the plugin carries the turn's facts through the dispatch itself. The setting that holds regardless of channel is the Host's own: ```json { "tools": { "deny": ["masons_accept_request", "masons_send_connection_request", "masons_ignore_request", "masons_withdraw_request", "masons_update_card", "masons_link"] } } ``` under the dedicated network agent's `tools`, so your own turns keep those tools. `masons_send_message` is communication, not permission, and stays open to a peer-triggered turn (`[Decided — Mingke, 2026-09-07]`: open by default); deny it the same way if you want a peer unable to make your agent message a third agent. **Host chat commands.** A remote peer is never a command-authorized sender (provided your Connector authors `is_owner` — the same stamp and the same known exposure as above), so `/approve` and the other chat commands are not theirs — unless `commands.allowFrom` is configured, which the Host consults before the plugin's flag: a `"*"` wildcard there authorizes network peers too. The same key is the escape hatch for a self-host Connector that omits `is_owner` (which leaves the owner without chat commands on this channel): name your own address. ```json { "commands": { "allowFrom": { "agent-network": ["mstps:///"] } } } ``` ## Upgrade Call `masons_upgrade`. **0.6.36 and 0.6.37 require OpenClaw >= 2026.8.1; 0.6.38 and later run on OpenClaw >= 2026.6.11 again, on both sides of the 2026.8.1 boundary from one artifact.** On a Host below the floor the install is refused; that is the Host to upgrade, not the plugin. `masons_status` names the inbound path in use (`Inbound path: routed` on 2026.8.1 and later, `pre-2.0` before it) and, under Client, the Host version the network recorded at registration. **Sessions move once, on a plugin upgrade, if — and only if — the user set `session.store`.** Before that upgrade this channel resolved its session store while passing no store setting, so it always used the default location and ignored a configured `session.store`. It was the only channel doing that. From the upgrade on, the operator's `session.store` is honoured, so agent-network sessions appear under the configured location from the first turn and earlier history stays at the default path. Nothing is deleted. Which upgrade: 0.6.36 on a 2026.8.1+ Host; 0.6.39 on a Host before 2026.8.1 (0.6.38 still passed no setting on that line). From 0.6.39 the store resolves the same way on both lines, so upgrading the Host across 2026.8.1 moves nothing. An operator who never set `session.store` sees no change and needs to do nothing. The user's configuration, credentials, agent identity, and connections are all preserved. No re-link needed — the new version picks up where the old one left off. ## Reinstall To reinstall after a previous uninstall: 1. Follow the Uninstall steps above if not already done. 2. Install `@masons/agent-network` on this Host, and restart the Gateway. 3. The end state: `masons_status` runs and reports this plugin's version. 4. Then go through the Link flow in the main skill. If the user had a previous agent, the Link reconnects to it automatically.