{"id":"add-matrix","name":"add-matrix","summary":"Chat SDKを通じてMatrixチャネル統合を追加してください。どのMatrixホームサーバーでも動作します。","body":"# Add Matrix Channel\n\nAdds Matrix support via the Chat SDK bridge. NanoClaw doesn't ship channels in\ntrunk — this skill copies the Matrix adapter in from the `channels` branch.\n\nThe mechanical steps under **Apply** carry `nc:` directive fences: an agent\nreads the prose and applies them, and a parser can apply them deterministically\nfrom the same document. Every directive is idempotent, so the whole skill is\nsafe to re-run; anything a parser can't apply falls back to the prose beside it.\n\n## Apply\n\n### 1. Copy the adapter\n\nFetch the `channels` branch and copy the Matrix adapter into `src/channels/`\n(overwrite — the branch is canonical):\n\n```nc:copy from-branch:channels\nsrc/channels/matrix.ts\nsrc/channels/matrix-registration.test.ts\n```\n\n### 2. Register the adapter\n\nAppend the self-registration import to the channel barrel (skipped if the line\nis already present). This one line is the skill's only reach-in into core:\n\n```nc:append to:src/channels/index.ts\nimport './matrix.js';\n```\n\n### 3. Configure the ESM patch\n\nThe published adapter references `matrix-js-sdk/lib/...` without `.js`\nextensions, which fails under Node 22 strict ESM resolution. Register the\ncommitted pnpm patch before installing the package. pnpm reapplies it after\nevery install and fails if the pinned package drifts away from the patch:\n\n```nc:copy\npatches/@beeper__chat-adapter-matrix@0.2.0.patch\n```\n\n```nc:run effect:refresh\npnpm pkg set 'pnpm.patchedDependencies[@beeper/chat-adapter-matrix@0.2.0]=patches/@beeper__chat-adapter-matrix@0.2.0.patch'\n```\n\n### 4. Install the adapter package\n\nPinned to an exact version — the supply-chain policy rejects ranges and `latest`.\nThe Matrix adapter lives in the `@beeper/` namespace and versions on its own\ntrack (not the `@chat-adapter/*` family), so it carries its own pin:\n\n```nc:dep\n@beeper/chat-adapter-matrix@0.2.0\n```\n\n### 5. Verify and build\n\nBuild guards the typed `createChatSdkBridge(...)` core call the adapter makes\nand fails if the `import './matrix.js';` line is missing. The direct Node import\nchecks the published ESM entrypoint using the real runtime resolver:\n\n```nc:run effect:build\npnpm run build\n```\n```nc:run effect:test\nnode --input-type=module -e 'await import(\"@beeper/chat-adapter-matrix\")'\n```\n```nc:run effect:test\npnpm exec vitest run src/channels/matrix-registration.test.ts\n```\n\n`matrix-registration.test.ts` imports the real channel barrel and asserts the\nregistry contains `matrix`. It goes red if the import line is deleted or drifts,\nif the barrel fails to evaluate, or if `@beeper/chat-adapter-matrix` isn't\ninstalled (the import throws) — so it also covers the dependency from step 3.\n\nEnd-to-end message delivery against a real Matrix homeserver is verified\nmanually once the service is running — see Next Steps.\n\n## Credentials\n\nThe bot needs its own Matrix account — separate from the user's account. This is\nrequired because Matrix cannot send DMs to yourself. These steps are human and\ninteractive (no parser can click through Element), so they stay prose.\n\n### Create a bot account\n\n1. Open [app.element.io](https://app.element.io) in a private/incognito window (or sign out first)\n2. Register a new account for the bot (e.g. `andybot` on matrix.org)\n3. Note the bot's user ID (e.g. `@andybot:matrix.org`)\n\n### Choose an auth method\n\n**Option A: Username + Password (simpler)**\n\nNo extra steps — just use the bot account's credentials directly. The adapter logs in automatically.\n\n```bash\nMATRIX_BASE_URL=https://matrix.org\nMATRIX_USERNAME=andybot\nMATRIX_PASSWORD=your-bot-password\nMATRIX_USER_ID=@andybot:matrix.org\nMATRIX_BOT_USERNAME=Andy\n```\n\n**Option B: Access Token (recommended for production)**\n\nGet an access token from Element: sign into the bot account → **Settings** > **Help & About** > **Access Token** (under Advanced). Or via API:\n\n```bash\ncurl -XPOST 'https://matrix.org/_matrix/client/r0/login' \\\n  -d '{\"type\":\"m.login.password\",\"user\":\"andybot\",\"password\":\"...\"}'\n```\n\n```bash\nMATRIX_BASE_URL=https://matrix.org\nMATRIX_ACCESS_TOKEN=your-access-token\nMATRIX_USER_ID=@andybot:matrix.org\nMATRIX_BOT_USERNAME=Andy\n```\n\n### Optional settings\n\n```bash\nMATRIX_INVITE_AUTOJOIN=true                    # Auto-accept room invites (default: true)\nMATRIX_INVITE_AUTOJOIN_ALLOWLIST=@you:matrix.org  # Only accept invites from these users\nMATRIX_RECOVERY_KEY=your-recovery-key          # Enable E2EE cross-signing\nMATRIX_DEVICE_ID=NANOCLAW01                    # Stable device ID across restarts\n```\n\n### Store the credentials\n\nCapture the values for the auth method you chose, then write them. `prompt` only\n*asks* and binds the answer to a name; a separate directive consumes it — so the\nsame prompts could feed `ncl` or the OneCLI vault instead of `.env` by swapping\nonly the consumer. The homeserver URL, the bot's user ID, and a display name are\nshared across both auth methods:\n\n```nc:prompt base_url\nPaste the homeserver base URL, e.g. `https://matrix.org`.\n```\n```nc:prompt user_id\nPaste the bot's full Matrix user ID, e.g. `@andybot:matrix.org`.\n```\n```nc:prompt bot_username\nPaste a display name for the bot, e.g. `Andy`.\n```\n```nc:env-set\nMATRIX_BASE_URL={{base_url}}\nMATRIX_USER_ID={{user_id}}\nMATRIX_BOT_USERNAME={{bot_username}}\n```\n\nFor **Option A** capture the bot login, for **Option B** capture the access\ntoken — set only the block matching your chosen method:\n\n```nc:prompt username\nOption A only — the bot's login username (the localpart, e.g. `andybot`).\n```\n```nc:prompt password secret\nOption A only — the bot account's password.\n```\n```nc:env-set\nMATRIX_USERNAME={{username}}\nMATRIX_PASSWORD={{password}}\n```\n```nc:prompt access_token secret\nOption B only — the access token from Element Settings > Help & About, or from the login API.\n```\n```nc:env-set\nMATRIX_ACCESS_TOKEN={{access_token}}\n```\n\n## Next Steps\n\nIf you're in the middle of `/setup`, return to the setup flow now.\n\nOtherwise, run `/manage-channels` to wire this channel to an agent group.\n\n## Channel Info\n\n- **type**: `matrix`\n- **terminology**: Matrix has \"rooms.\" A room can be a group chat or a direct message. Rooms have internal IDs (like `!abc123:matrix.org`) and optional aliases (like `#general:matrix.org`).\n- **how-to-find-id**: For DMs, use the bot's `openDM` to resolve the room automatically. For group rooms, in Element click the room name > Settings > Advanced — the \"Internal room ID\" is the platform ID (starts with `!`). Or use a room alias like `#general:matrix.org`.\n- **supports-threads**: partial (some clients support threads, but not all — treat as no for reliability)\n- **typical-use**: Interactive chat — rooms or direct messages. Requires a separate bot account (the agent cannot DM users from their own account).\n- **default-isolation**: Same agent group for rooms where you're the primary user. Separate agent group for rooms with different communities or sensitive contexts.\n\n## Troubleshooting\n\n**Build fails with `ERR_MODULE_NOT_FOUND` for `matrix-js-sdk/lib/...`.** The ESM extension patch (step 4) hasn't been applied — or a later `pnpm install` reinstalled the adapter and wiped it. Re-run the patch, then `pnpm run build`; the patch is idempotent, so re-running is always safe.\n\n**Login fails with `M_FORBIDDEN`.** The username/user-ID split is the usual trip: `MATRIX_USERNAME` is the bare localpart (`andybot`), while `MATRIX_USER_ID` is the full ID (`@andybot:matrix.org`) — swapping them fails auth. With Option B, an access token dies the moment that Element session signs out; grab a fresh one from Settings → Help & About → Access Token, or via the login API.\n\n**The bot never joins your room.** Auto-join is on by default (`MATRIX_INVITE_AUTOJOIN=true`), but an allowlist (`MATRIX_INVITE_AUTOJOIN_ALLOWLIST`) that doesn't include your user ID makes it ignore your invites. Invite the bot from your own account and watch the service log for the join.\n\n**Messages to yourself never arrive.** Matrix cannot DM your own account — the bot must be its own account, separate from yours. If you configured the adapter with your personal credentials, register a dedicated bot account and redo the credential steps.\n\n**Registered but silent.** Run `pnpm exec vitest run src/channels/matrix-registration.test.ts` — red means the barrel import or the `@beeper/chat-adapter-matrix` install drifted, so re-run the Apply steps. If green, restart the service (see Next Steps) and check `logs/nanoclaw.error.log` for login errors.","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-matrix","license":"MIT","category":"writing","lang":"en","tokens":2106,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"apply-fixtures.json","size":664,"sha256":"8b2c6392c33f05ede9e6b97a674b8e64282651bacafe2b425a7d46705401dbe1"},{"path":"patches/@beeper__chat-adapter-matrix@0.2.0.patch","size":1061,"sha256":"d8f9cda088701285b3be191ea30edfd2e96ccb7b97f2934fa8c26c1fa424c020"},{"path":"REMOVE.md","size":1021,"sha256":"d175094d3fb1edc6879fdf609340549711c16102a8a9096d2c940966f8a8c616"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["app.element.io","matrix.example.com","matrix.org"]}}