@matelink/cli 2026.4.7

package/README.md

@@ -0,0 +1,180 @@
+# @matelink/cli
+
+Relay-first standalone CLI for pairing a mobile client with an OpenClaw host and
+keeping a relay bridge online.
+
+## 1) Install
+
+Install standalone CLI:
+
+```bash
+# global
+npm i -g @matelink/cli
+
+# or one-off
+npx @matelink/cli pair
+```
+
+CLI commands:
+
+```bash
+matecli setup
+matecli pair
+matecli pair 123456
+matecli pair --code 123456
+matecli bridge
+matecli pair-url
+matecli status
+```
+
+Recommended first-run flow after `npm i -g @matelink/cli`:
+
+```bash
+# 1) prepare OpenClaw config + permissions
+matecli setup --relay http://<relay-host>:8090 --public-base http://<gateway-public-host>:<port>
+
+# 2) then pair and keep relay bridge online (short form)
+matecli pair 123456 --serve-relay
+```
+
+Relay-aware pairing (auto publish + local bind worker):
+
+```bash
+matecli pair --relay http://<relay-host>:8090 --wait-bind --serve-relay
+matecli pair --code 123456 --relay http://<relay-host>:8090 --wait-bind --serve-relay
+# or set once:
+export TESTNEXTIM_RELAY_URL=http://<relay-host>:8090
+matecli pair --wait-bind --serve-relay
+```
+
+When relay is configured, `pair` publishes `{code, bindUrl, gatewayBaseUrl, relayGatewayId, relayClientToken, relayGatewayToken}` to:
+
+`POST /v1/pair-sessions`
+
+And in `--wait-bind` mode it also runs a local bind worker:
+
+- Polls relay `GET /v1/pair-sessions/{code}/bind-requests/next`
+- Records the bind result in local CLI state
+- Reports result via `POST /v1/pair-sessions/{code}/bind-results`
+
+In `--serve-relay` mode, CLI also keeps a chat bridge online:
+
+- Polls relay `GET /v1/gateways/{gatewayId}/requests/next`
+- Calls local gateway `POST /v1/responses`
+- Streams chunks back through `POST /v1/gateways/{gatewayId}/requests/{requestId}/events`
+
+## 2) Configure minimum fields
+
+```bash
+matecli setup --relay http://<relay-host>:8090 --public-base https://gw.example.com
+```
+
+This prepares the local OpenClaw gateway for `/v1/responses`, stores relay
+credentials in `~/.openclaw/testnextim.state.json`, and keeps plugin config out
+of `openclaw.json`.
+
+## 3) QR login flow
+
+Start OpenClaw first, then pair from the app:
+
+```bash
+openclaw gateway run --bind loopback --port 18789 --force
+```
+
+Use the mobile app to generate a pairing code, then run:
+
+```bash
+matecli pair 123456 --serve-relay
+```
+
+### 4.3 Check active bind state (optional)
+
+`GET {bindPublicBaseUrl}{bindPath}?accountId=default`
+
+Response includes current active `code`, `bindUrl`, and `expiresAt` if a pairing session is active.
+
+The plugin validates DM policy and pairing, dispatches to OpenClaw, and sends replies to your IM backend via:
+
+`POST {apiBaseUrl}/messages`
+
+Payload:
+
+```json
+{
+  "to": "im-user-123",
+  "text": "reply text",
+  "mediaUrl": "https://...",
+  "replyToId": "msg-1"
+}
+```
+
+## 5) Modify config from IM + restart
+
+This plugin enables config commands by default when setup/bind succeeds.
+
+In chat:
+
+```text
+/config set channels.testnextim.allowFrom ["im-user-123","im-admin-1"]
+/config set channels.testnextim.configWrites true
+/restart
+```
+
+Notes:
+
+- most `channels.*` updates hot-reload
+- gateway/network base settings usually require restart
+
+## 6) Optional environment secrets
+
+You can provide secrets by environment instead of config file:
+
+- `TESTNEXTIM_ACCESS_TOKEN`
+- `TESTNEXTIM_APP_SECRET`
+- `OPENCLAW_TESTNEXTIM_PUBLIC_BASE_URL`
+- `OPENCLAW_TESTNEXTIM_GATEWAY_BASE_URL`
+
+Compatibility:
+
+- Legacy `channels.custom-im.*` config keys are still read during migration.
+- Legacy headers `x-custom-im-token` and `x-custom-im-app-secret` are still accepted.
+
+## 7) Relay architecture requirement
+
+Relay is optional for traditional direct bind, but strongly recommended for mobile pairing when OpenClaw is behind NAT or has no public gateway URL.
+
+- Direct mode: app calls your gateway bind URL directly.
+- Relay worker mode (`matecli pair --wait-bind`): app only talks to relay, server-side CLI does local bind on behalf of app.
+- Relay bridge mode (`matecli pair --serve-relay` or `matecli bridge`): app chat traffic goes through relay, and host-side CLI forwards to local `127.0.0.1` gateway.
+
+## 8) Go Relay Server (Pair Session Bus)
+
+Server path:
+
+`extensions/testnextim/relay-server`
+
+Run:
+
+```bash
+cd extensions/testnextim/relay-server
+go run .
+```
+
+Environment:
+
+- `TESTNEXTIM_RELAY_PORT` (default `8090`)
+- `TESTNEXTIM_RELAY_TOKEN` (optional bearer token for publish/worker endpoints)
+- `TESTNEXTIM_RELAY_DEFAULT_TTL_SECONDS` (default `600`)
+
+API:
+
+- `POST /v1/pair-sessions` create/update pair session
+- `GET /v1/pair-sessions/{code}` query pair session (app side)
+- `POST /v1/pair-sessions/{code}/consume` mark consumed
+- `GET /v1/pair-sessions/{code}/events` SSE stream for status updates
+- `POST /v1/pair-sessions/{code}/bind` app submits bind payload and waits for worker result
+- `GET /v1/pair-sessions/{code}/bind-requests/next` worker polls pending bind requests
+- `POST /v1/pair-sessions/{code}/bind-results` worker reports local gateway bind result
+- `GET /v1/gateways/{gatewayId}/requests/next` gateway bridge polls pending chat requests
+- `POST /v1/gateways/{gatewayId}/requests/{requestId}/events` gateway bridge streams relay events
+- `POST /v1/openclaw/responses` app chat endpoint (supports `gatewayId + clientToken`)