Cxc Remote

remote — Messenger Bridge Setup Ladder

Use this skill when the user wants codexclaw reachable from Telegram or Discord ("텔레그램 연결해줘", "connect discord", "set up remote"). The agent runs every step below itself and verifies each one; the user is only needed for the two steps a bot platform requires a human for (creating the bot and tapping the pairing trigger).

All API calls target the local bridge at http://127.0.0.1:7717. Every mutating request MUST send BOTH headers, or the server answers 403:

bashCopy code
-H 'content-type: application/json' -H 'x-codexclaw-local: 1'

Ladder (both platforms)

1. Preflight — is the bridge up? curl -s http://127.0.0.1:7717/api/health -> {"ok":true,...}. Not running? Foreground: cxc serve --port 7717 --cwd <project>. Daemon (macOS launchd): cd <project> FIRST (install binds the current working directory as --cwd), then cxc service install --port 7717. Check with cxc service status; logs at ~/.codexclaw/serve.{out,err}.log. There is no serve status subcommand. On Linux, use systemd user units. On Windows, use Task Scheduler. See platform-specific sections in references/telegram.md and references/discord.md.
2. Token (human step). Walk the user through bot creation — exact steps in references/telegram.md / references/discord.md. Never echo the token into logs, commit it, or paste it back in chat responses.
3. Create the named agent (validates the token). GET /api/agents to see existing ones. New: POST /api/agents with {"name":"...","kind":"telegram"|"discord","token":"..."} — the server validates via TG getMe / DC users/@me and answers 400 on a bad token (stop and re-ask), 200 with username/botId on success. Existing agent: POST /api/agents/update with {"id":<n>,"token":"..."} (same validation). Then POST /api/agents/enable with {"id":<n>,"enabled":true}.
4. Pair the chat (human tap). Snapshot the baseline first: GET /api/agents/handshake/status?id=<n> -> note allowlistCount.
   • TG preferred — one-tap deep link: POST /api/agents/pairing-link with {"id":<n>,"seconds":600} (default 600, cap 3600) returns {"ok":true,"url":"https://t.me/<bot>?start=<code>","code":..., "expiresAt":...}. Send the url to the user; tapping it makes Telegram send /start <code> — the code is single-use and TTL-bounded, no open window needed. Never paste the code anywhere else.
   • Window fallback (and the only DC path): POST /api/agents/handshake/open with {"id":<n>,"seconds":120} (default 120, cap 600); the user sends /start (TG) or types !cxc start in a channel the bot can read (DC — pairing is a text trigger; slash commands reject unpaired channels). Either way, poll the status endpoint: pairing succeeded when allowlistCount grows past the baseline; on expiry mint a fresh link or reopen the window.
5. Smoke test. POST /api/agents/test-send with {"id":<n>} messages the newest paired chat (an explicit "chatId" must already be paired; 400 otherwise). Then have the user send /status (TG) or !cxc status (DC) — the first gateway command creates the binding row, and only THEN does GET /api/bindings show it.
6. Anything wrong -> references/troubleshooting.md (symptom -> cause -> fix, all distilled from real incidents).

Platform references

Human-facing overview: the bridge README (served at http://127.0.0.1:7717/readme while the bridge runs).

• references/telegram.md — BotFather steps, TG command surface, forum-topic sessions, optional webhook mode (HTTPS /webhook/telegram/<secret>, auto-fallback to long-poll).
• references/discord.md — Developer Portal steps, Message Content intent, invite URL (scope=bot&permissions=3072), slash vs text command split, thread mode (slash: /mode value:thread|plain; text: !cxc mode thread|plain).

Scope guard

• The GUI at http://127.0.0.1:7717 can do this visually: the Agents page is the named-agent setup flow (same /api/agents/* surface); the Channels page is the legacy single-channel shim. Offer the Agents page when the user prefers clicking over chat.
• /api/connect/* is the legacy single-channel shim (its validate even stores the token as a side effect); teach and use the /api/agents/* surface.
• This skill configures the bridge only. Bridge behavior changes (commands, adapters, gates) are cxc-dev territory, not setup.