Operator-UI: optional terminal client for AKS sandboxes via openclaw-node (VAP-safe)

[pallakatos]

Problem

The azureclaw-sandbox-exec-ban ValidatingAdmissionPolicy correctly blocks kubectl exec/attach into the openclaw container in AKS for security reasons (preserves seccomp/egress-guard/Landlock boundaries, prevents token leakage from /proc, blocks MCP02 tool poisoning). The current operator-UI "Connect" path now uses port-forward + WebUI URL — VAP-safe, zero install — but operators have asked for a terminal/TTY experience equivalent to local-Docker dev.

Constraints

• Must not exec into the openclaw container (VAP-blocked, and intentionally so).
• Must not require installing the full openclaw npm package on the operator's laptop (heavyweight, runs an agent runtime locally we don't want).
• Should add minimal code we have to maintain — the gateway WS protocol is openclaw-versioned (currently v3) and we don't want to track its drift.

Investigation summary

Surveyed openclaw-org packages (acpx, clawgo, etc.) — none are remote-gateway-only TUI clients. acpx is a coding-agent harness that spawns a local openclaw acp bridge (which still requires the full openclaw install). clawgo is for IoT/voice nodes.

Found a community-maintained client library: `openclaw-node`.

Property	Value
Description	Node.js client for the OpenClaw Gateway WebSocket protocol
Size	86 KB unpacked, zero runtime deps
License	MIT
Repo	https://github.com/heypinchy/openclaw-node
Provenance	npm SLSA v1 attestation
Cadence	18 versions since Feb 2026, last release 2026-05-05
Adoption	~5k downloads/month, 11★
Maintainer	`jaias` (single npm maintainer; `heypinchy` is the GH org behind Pinchy web UI)
Node	Built-in WebSocket on Node 22+ — no `ws` dep needed (CLI already requires Node 22+)

API matches our needs cleanly: AsyncIterator `client.chat()` with `text` / `tool_use` / `tool_result` chunks, handles handshake/auth/keepalive.

Proposal

Add a `--tui` flag to `azureclaw connect` (AKS branch) that:

1. Reuses existing port-forward + `gateway-token` Secret fetch (already implemented for the WebUI path).
2. Hands off to a small chat loop using `openclaw-node` pointed at `ws://localhost:18789`.
3. Mirrors in the operator-UI dialog as a second action alongside the existing "WebUI URL" action.

Default behavior (no flag) stays as-is: print WebUI URL.

Estimated implementation: ~80 LOC in `cli/src/commands/connect/tui.ts`.

Trust mitigations (required before merge)

`openclaw-node` is third-party with a single maintainer and ~2.5 month track record. Apply the same vendoring discipline we already use for `@agentmesh/sdk`:

1. Pin exact version (no `^` range) in `cli/package.json`.
2. Vendor `dist/` under `vendor/openclaw-node/` with README documenting:
   • Source repo + commit hash
   • Audit date + auditor
   • npm `sha512` integrity hash
   • Version
3. Bump only with deliberate re-audit, mirroring the existing AGT SDK patch workflow.
4. Risk acceptance: client runs on operator's laptop only. Worst-case compromise = token + chat-content exfil from operator machine. Not in AKS/agent sandbox blast radius.

Acceptance criteria

• `vendor/openclaw-node/` added with README + integrity hash + audit notes
• `cli/package.json` pins exact version, file: reference resolves to vendored dir
• `azureclaw connect --tui` works against an AKS sandbox via existing port-forward + token flow
• Operator-UI dialog adds "Terminal" action, mirroring "WebUI URL" action; both VAP-safe
• Help text documents that `--tui` requires no separate install
• No exec into openclaw container; VAP remains enforced

Out of scope

• Replacing the WebUI default — WebUI stays the canonical zero-install path.
• Implementing our own WS protocol client — explicitly rejected to avoid tracking openclaw protocol drift.
• Local-dev path — already works via existing exec-into-Docker (no VAP locally).

Related

• VAP definition: `deploy/helm/azureclaw/templates/admission-pod-exec-ban.yaml`
• Current AKS connect: `cli/src/commands/connect.ts:134-202`
• Operator-UI dialog: `cli/src/commands/operator/dialogs/connect.ts`
• Vendoring precedent: `vendor/agentmesh-sdk/` (8 patches, README documents each)