ag-ents OpenClaw Channel

@ag-ents/ag-ents-plugin is the OpenClaw channel plugin for the ag-ents MVP Path B validation lane.

Current package status:

• onboarding validates the real /ws/agent handshake before writing config
• config stays locked under channels["ag-ents"]
• one persistent agent WebSocket is maintained per enabled ag-ents account
• guided deployments may run multiple enabled ag-ents accounts in one OpenClaw runtime as long as each account is still routed to its own personal agent workspace
• text, status_update, and approval_card route over the authenticated gateway connection
• send_status_update and send_approval_card are registered as the only plugin-owned custom tools in MVP
• reconnect backoff, heartbeat ping/pong, pending approval resume, and minimal config_changed drift surfacing are implemented

Install and Link

Build the package first:

pnpm --filter @ag-ents/ag-ents-plugin build

Then install it into a local OpenClaw runtime from this workspace path or from npm:

• local path: packages/openclaw-channel-ag-ents
• npm package: @ag-ents/ag-ents-plugin
• linked-install catalog: packages/openclaw-channel-ag-ents/openclaw.channel-catalog.json

If you are doing the first linked OpenClaw smoke for EPIC-04, use the dedicated runbook:

• /Users/sogo/Documents/Projects/ag-ents/docs/implementation/epics/EPIC-04-existing-openclaw-agent-path/TICKET-04-existing-agent-acceptance-and-recovery/manual-linked-openclaw-smoke-runbook.md

That runbook covers:

• first-time disposable oc setup and oc onboard
• local plugin link-install
• openclaw channels add --channel ag-ents
• text, approval, reconnect, and config-drift verification

Onboarding

Interactive path:

export OPENCLAW_PLUGIN_CATALOG_PATHS="/Users/sogo/Documents/Projects/ag-ents/packages/openclaw-channel-ag-ents/openclaw.channel-catalog.json"
openclaw channels add

Then choose ag-ents in the channel picker.

Direct non-interactive path:

export OPENCLAW_PLUGIN_CATALOG_PATHS="/Users/sogo/Documents/Projects/ag-ents/packages/openclaw-channel-ag-ents/openclaw.channel-catalog.json"
openclaw channels add --channel ag-ents --url http://127.0.0.1:8787 --token agtok_...

For linked installs against OpenClaw 2026.3.24, that exported catalog path is required. openclaw plugins install -l ... records the package under plugins.load.paths, which is enough for runtime loading and plugins inspect, but this OpenClaw build resolves channels add through its channel catalog and does not catalog plugins.load.paths. Also note that --channel ag-ents uses the direct-input path, so you must provide --token explicitly if you use it.

The ag-ents setup flow also merges send_status_update and send_approval_card into tools.alsoAllow. That is required when the OpenClaw profile keeps tools.profile: "coding", because the coding profile otherwise filters plugin tools out of the live agent tool inventory.

If you still see Unknown channel: ag-ents, verify that:

• OPENCLAW_PLUGIN_CATALOG_PATHS points at the checked-in catalog file above
• openclaw plugins inspect ag-ents shows the linked package as loaded

For the published npm package used by the native VPS lane, also verify the installed version is 0.1.1 or newer. The earlier 0.1.0 publish still advertised TypeScript OpenClaw entrypoints and can leave the runtime with a recorded plugin install but no registered ag-ents channel.

The wizard asks for:

• ag-ents base URL
• one per-agent token (agent.agentToken, usually agtok_..., not session.accessToken)

It still configures one account at a time. Guided Path A may manage several accounts in one runtime, but MVP delivery remains one personal agent thread per account.

It validates those credentials by opening a short-lived connection to /ws/agent, waiting for the gateway authenticated frame, and then closing immediately.

Manual Config Fallback

Manual JSON editing is supported as a fallback only:

{
  "tools": {
    "alsoAllow": ["send_status_update", "send_approval_card"]
  },
  "channels": {
    "ag-ents": {
      "accounts": {
        "default": {
          "enabled": true,
          "baseUrl": "https://api.ag-ents.chat",
          "token": "agtok_..."
        }
      },
      "defaultAccount": "default",
      "dmPolicy": "allowlist",
      "groupPolicy": "disabled"
    }
  }
}

Notes:

• if an older linked profile already exists without tools.alsoAllow, rerun openclaw channels add --channel ag-ents --url ... --token agtok_... after pulling the latest repo state so the setup flow rewrites the missing tool allowlist
• groupPolicy stays locked to "disabled" for MVP.
• dmPolicy is kept for OpenClaw compatibility, but MVP delivery still targets one linked personal_agent_thread per configured account.
• token is redacted in inspect and status surfaces.
• Unsupported gateway config_push and command frames are logged and ignored in MVP.

Local Verification

pnpm --filter @ag-ents/ag-ents-plugin typecheck
pnpm --filter @ag-ents/ag-ents-plugin test
pnpm --filter @ag-ents/ag-ents-plugin build