{"id":"add-deltachat","name":"add-deltachat","summary":"@deltachat/stdio-rpc-server経由でDeltaChatのチャネル統合を追加してください。","body":"# Add DeltaChat Channel\n\nThe adapter drives the `@deltachat/stdio-rpc-server` JSON-RPC subprocess directly — pure Node.js against the DeltaChat core library. Messages are delivered over email with Autocrypt/OpenPGP encryption.\n\n## Install\n\n### 1. Copy the adapter and its registration test\n\nFetch the `channels` branch from the configured remote that carries it, then\noverwrite the skill-owned files with the canonical registry copies:\n\n```nc:copy from-branch:channels\nsrc/channels/deltachat.ts\nsrc/channels/deltachat-registration.test.ts\n```\n\n### 2. Append the self-registration import\n\nAppend to `src/channels/index.ts` (skip if already present):\n\n```nc:append to:src/channels/index.ts\nimport './deltachat.js';\n```\n\n### 3. Install the adapter package (pinned)\n\n```nc:dep\n@deltachat/stdio-rpc-server@2.49.0\n```\n\n### 4. Build and validate\n\n```nc:run effect:build\npnpm run build\n```\n```nc:run effect:test\npnpm exec vitest run src/channels/deltachat-registration.test.ts\n```\n\nBoth must be clean before proceeding. `deltachat-registration.test.ts` is the one integration test: it imports the real channel barrel and asserts the registry contains `deltachat`. It goes red if the `import './deltachat.js';` line is deleted or drifts, if the barrel fails to evaluate (so the channel genuinely would not register), or if `@deltachat/stdio-rpc-server` isn't installed (the import throws) — so it also implicitly verifies the dependency from step 4. Importing is safe: deltachat instantiates the rpc client only in `setup()` (at host startup), never at import.\n\nEnd-to-end message delivery against a real email account is verified manually once the service is running — see Wiring and Troubleshooting.\n\n## Account Setup\n\nA dedicated email account is strongly recommended — it will accumulate DeltaChat-formatted messages and store encryption keys. Not all providers work well with DeltaChat; check https://providers.delta.chat/ before picking one.\n\n**Default security modes:** IMAP uses SSL/TLS (port 993), SMTP uses STARTTLS (port 587). Both are configurable via `.env` — see Credentials below.\n\nTo find the correct hostnames for a domain:\n\n```bash\nnode -e \"require('dns').resolveMx('example.com', (e,r) => console.log(r))\"\n```\n\nMost providers publish their IMAP/SMTP hostnames in their help docs under \"manual setup\" or \"IMAP access.\"\n\n## Credentials\n\nAdd to `.env`:\n\n```bash\nDC_EMAIL=bot@example.com\nDC_PASSWORD=your-app-password\nDC_IMAP_HOST=imap.example.com\nDC_IMAP_PORT=993\nDC_IMAP_SECURITY=1        # 1=SSL/TLS (default), 2=STARTTLS, 3=plain\nDC_SMTP_HOST=smtp.example.com\nDC_SMTP_PORT=587\nDC_SMTP_SECURITY=2        # 2=STARTTLS (default), 1=SSL/TLS, 3=plain\n```\n\nSecurity settings are applied on every startup, so changing them in `.env` and restarting takes effect without wiping the account.\n\n\n### Optional settings\n\nThe following are read from the process environment (not `.env`). To override them, add `Environment=` lines to the systemd service unit or your launchd plist:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `DC_ACCOUNT_DIR` | `dc-account` | Directory for DeltaChat account data (IMAP state, keys, blobs) |\n| `DC_DISPLAY_NAME` | `NanoClaw` | Bot display name shown in DeltaChat |\n| `DC_AVATAR_PATH` | _(none)_ | Absolute path to avatar image; set at startup only |\n\nThe `/set-avatar` command (send an image with that caption) is the easiest way to set the avatar at runtime without modifying the service file. Only users with `owner` or global `admin` role can use it.\n\n### Restart\n\nRun from your NanoClaw project root:\n\n```bash\nsource setup/lib/install-slug.sh\n\n# Linux\nsystemctl --user restart $(systemd_unit)\n\n# macOS\nlaunchctl kickstart -k gui/$(id -u)/$(launchd_label)\n```\n\nOn first start the adapter configures the email account (IMAP/SMTP credentials, calls `configure()`). Subsequent starts skip straight to `startIo()`. Account data is stored in `dc-account/` in the project root (or your `DC_ACCOUNT_DIR`).\n\n## Wiring\n\n### DMs\n\n**DeltaChat contacts cannot be added by email alone** — to start a chat, the user must open the bot's invite link in their DeltaChat app or scan its QR code. This triggers the SecureJoin handshake.\n\n#### Step 1 — Get the invite link\n\nAfter the service starts, the adapter logs the invite URL and writes a QR SVG:\n\n```bash\ngrep \"invite link\" logs/nanoclaw.log | tail -1\n# url field contains the https://i.delta.chat/... invite link\n# also written to dc-account/invite-qr.svg (or $DC_ACCOUNT_DIR/invite-qr.svg)\n```\n\nThe invite URL is stable (tied to the bot's email and encryption keys) so it stays valid across restarts.\n\n#### Step 2 — Add the bot in DeltaChat\n\nTwo options for the user to connect:\n\n- **Link**: Copy the `https://i.delta.chat/...` URL and open it on the device running DeltaChat. The app recognises it and shows a \"Start chat\" prompt.\n- **QR code**: Open `dc-account/invite-qr.svg` in a browser or image viewer, display it on screen, and scan it from the DeltaChat app using the QR-scan button on the new-chat screen.\n\nAfter accepting, DeltaChat exchanges keys and creates the chat automatically.\n\n#### Step 3 — Wire the chat to an agent\n\nOnce the first message arrives the router auto-creates a `messaging_groups` row. Look up the chat ID:\n\n```bash\npnpm exec tsx scripts/q.ts data/v2.db \\\n  \"SELECT platform_id, name FROM messaging_groups WHERE channel_type='deltachat' AND is_group=0 ORDER BY created_at DESC LIMIT 5\"\n```\n\nThen run `/init-first-agent` — it creates the agent group, grants the user owner access, and wires the messaging group in one step:\n\n```bash\npnpm exec tsx scripts/init-first-agent.ts \\\n  --channel deltachat \\\n  --user-id deltachat:user@example.com \\\n  --platform-id <platform_id from above> \\\n  --display-name \"Your Name\"\n```\n\n### Groups\n\nAdd the bot email to a DeltaChat group. When any member sends a message, the router creates a `messaging_groups` row with `is_group = 1`. Run `/manage-channels` to wire it to an agent group, or wire it directly with `ncl` — **the host service must be running** (`ncl` connects to it over a Unix socket):\n\n```bash\n# Engage mode/pattern default to the DeltaChat adapter's declared channel\n# defaults — for DeltaChat groups that's a name pattern (the platform has no\n# mention metadata), so the agent responds when addressed by name.\nncl wirings create --messaging-group-id <mg-id> --agent-group-id <ag-id>\n```\n\n## Next Steps\n\nIf you're in the middle of `/setup`, return to the setup flow now.\n\nOtherwise, run `/init-first-agent` to create an agent and wire it to your DeltaChat DM (see Wiring above), or `/manage-channels` to wire this channel to an existing agent group.\n\n## Channel Info\n\n- **type**: `deltachat`\n- **terminology**: DeltaChat calls them \"chats\" (1:1 DMs) and \"groups\"\n- **supports-threads**: no — DeltaChat has no thread model\n- **platform-id-format**: numeric chat ID as a string (e.g. `\"12\"`) — the DeltaChat core's internal chat identifier\n- **user-id-format**: `deltachat:{email}` — the contact's email address\n- **how-to-find-id**: Send a message from DeltaChat to the bot email, then query `messaging_groups` as shown above\n- **typical-use**: Personal assistant over DeltaChat DMs; small groups where participants use DeltaChat\n- **default-isolation**: One agent per bot identity. Multiple chats with the same operator can share an agent group; groups with other people should typically get their own agent group (the default `shared` session mode already gives each messaging group its own session)\n\n### Features\n\n- File attachments — inbound and outbound; inbound waits up to 30 seconds for large-message download to complete\n- Invite link logged on every startup — URL + QR SVG written to `dc-account/invite-qr.svg`; see Wiring for the bootstrap flow\n- `/set-avatar` — send an image with this caption to change the bot's DeltaChat avatar (admin/owner only)\n- Connectivity watchdog — restarts IO if IMAP goes quiet for 20 minutes or connectivity drops below threshold for two consecutive 5-minute checks\n- Network nudge — `maybeNetwork()` called every 10 minutes to recover from prolonged idle\n\nNot supported: DeltaChat reactions, message editing/deletion, read receipts.\n\n### Connectivity model\n\n`isConnected()` returns `true` when the internal connectivity value is ≥ 3000:\n\n| Range | Meaning |\n|-------|---------|\n| 1000–1999 | Not connected |\n| 2000–2999 | Connecting |\n| 3000–3999 | Working (IMAP fetching) |\n| ≥ 4000 | Fully connected (IMAP IDLE) |\n\n## Troubleshooting\n\n### Adapter not starting — credentials missing\n\n```bash\ngrep \"Channel credentials missing\" logs/nanoclaw.log | grep deltachat\n```\n\nAll six required vars (`DC_EMAIL`, `DC_PASSWORD`, `DC_IMAP_HOST`, `DC_IMAP_PORT`, `DC_SMTP_HOST`, `DC_SMTP_PORT`) must be present in `.env`.\n\n### Account configure fails\n\n```bash\ngrep \"DeltaChat\" logs/nanoclaw.log | tail -20\n```\n\nCommon causes:\n- Wrong IMAP/SMTP hostnames — double-check provider docs\n- App password not generated — Gmail and some others require this when 2FA is enabled\n- Port/security mismatch — defaults are port 993 + SSL/TLS for IMAP and port 587 + STARTTLS for SMTP; override with `DC_IMAP_PORT`/`DC_IMAP_SECURITY` or `DC_SMTP_PORT`/`DC_SMTP_SECURITY` in `.env`\n\n### Provider uses SMTP port 465 (SSL/TLS) instead of 587\n\nSet `DC_SMTP_SECURITY=1` and `DC_SMTP_PORT=465` in `.env`, then restart.\n\n### Messages not arriving\n\n1. Check the service is running and the adapter started: `grep \"Channel adapter started.*deltachat\" logs/nanoclaw.log`\n2. Check connectivity: `grep \"DeltaChat: IO started\" logs/nanoclaw.log`\n3. Check the sender has been granted access — run `/init-first-agent` to create their user record and wire the chat\n4. Verify the messaging group is wired: `pnpm exec tsx scripts/q.ts data/v2.db \"SELECT mg.platform_id, mga.agent_group_id FROM messaging_groups mg JOIN messaging_group_agents mga ON mg.id = mga.messaging_group_id WHERE mg.channel_type='deltachat'\"`\n\n### Stale lock file after crash\n\n```bash\nrm -f dc-account/accounts.lock\nsystemctl --user restart \"$(. setup/lib/install-slug.sh && systemd_unit)\"\n```\n\n### Bot not responding after restart\n\nThe account is already configured — IO restarts automatically on service start. If the RPC subprocess is stuck, restart the service. Check for errors:\n\n```bash\ngrep \"DeltaChat\" logs/nanoclaw.error.log | tail -20\n```\n\n### Messages received but agent not responding\n\nThe messaging group exists but may not be wired to an agent group. Run:\n\n```bash\npnpm exec tsx scripts/q.ts data/v2.db \"SELECT id, platform_id, name FROM messaging_groups WHERE channel_type='deltachat'\"\n```\n\nIf the group has no entry in `messaging_group_agents`, wire it with `/manage-channels`.","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/add-deltachat","license":"MIT","category":"writing","lang":"en","tokens":2649,"stars":0,"calls30d":1,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"REMOVE.md","size":1391,"sha256":"4410425cce0a09439f7247184f04ea1599820610e09c86cf263e12833959b82d"}],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":["i.delta.chat","providers.delta.chat"]}}