{"id":"manage-channels","name":"manage-channels","summary":"チャネルをエージェントグループに有線接続し、アイソレーションレベルを管理し、新しいチャネルグループを追加します。","body":"# Manage Channels\n\nWire messaging channels to agent groups. See `docs/isolation-model.md` for the full isolation model.\n\nPrivilege is a **user-level** concept, not a channel-level one (see `src/modules/permissions/db/user-roles.ts`, `src/modules/permissions/access.ts`). There is no \"main channel\" / \"main group\" — any user can be granted `owner` or `admin` (global or scoped to an agent group) via `grantRole()`, and messages from unknown senders are gated per-messaging-group by `unknown_sender_policy` (`strict` | `request_approval` | `public`).\n\n## Assess Current State\n\nRead the central DB (`data/v2.db`) using these canonical queries (column names match the schema, not the CLI flags — the `register` command's `--assistant-name` is stored in `agent_groups.name`).\n\nRun each via the in-tree wrapper — the host setup deliberately ships no `sqlite3` CLI:\n\n```bash\npnpm exec tsx scripts/q.ts data/v2.db \"<query>\"\n```\n\n```sql\nSELECT id, name AS assistant_name, folder, agent_provider FROM agent_groups;\nSELECT id, channel_type, platform_id, name, unknown_sender_policy FROM messaging_groups;\nSELECT messaging_group_id, agent_group_id, engage_mode, engage_pattern, session_mode, threads, priority FROM messaging_group_agents;\nSELECT user_id, role, agent_group_id FROM user_roles ORDER BY role='owner' DESC;\n```\n\nAlso check `.env` for channel tokens and `src/channels/index.ts` for uncommented imports.\n\nCategorize channels as: **wired** (has DB entities + messaging_group_agents row), **configured but unwired** (has credentials + barrel import, no DB entities), or **not configured**.\n\nIf the instance has no owner yet (`SELECT COUNT(*) FROM user_roles WHERE role='owner' AND agent_group_id IS NULL` returns 0), tell the user they should run `/init-first-agent` first — it stands up the first agent group, promotes the operator to owner, and verifies delivery end-to-end by having the agent DM them. Then return here for any additional channels/groups.\n\n## First Channel (No Agent Groups Exist)\n\n**Delegate to `/init-first-agent`.** It handles: channel choice, operator identity lookup, DM platform id resolution (with cold-DM or pair-code fallback), agent group creation, wiring, and the welcome DM. Return here afterward for any additional channels.\n\n## Channel Defaults: The Two-Level Model\n\nWiring defaults (engage mode/pattern, threading, `unknown_sender_policy`) resolve through **exactly two levels**:\n\n1. **Adapter declaration** — each channel adapter declares `ChannelDefaults` (separate DM and group contexts, plus a `mentions` capability) in its source file. The adapter copy is skill-installed and user-owned: to change a default install-wide, edit `src/channels/<channel>.ts` and restart. Declarations are never persisted to the DB.\n2. **Per-wiring/per-mg values chosen at creation** — every creation surface (`ncl wirings create` / `ncl messaging-groups create`, the `register` wizard step, the approval-card flow, `/init-first-agent`) fills omitted fields from the declaration and stores the result on the row. Pass explicit flags to override one wiring.\n\nThere is no third level: existing rows are never re-resolved, so editing a declaration only affects wirings created afterward. The one exception is the **`threads` column**, which stays live — `NULL` means \"inherit the declaration at message time\".\n\nChannels with no declaration (stale adapter copies) fall back to the legacy behavior; run `/update-skills` to pull current adapters.\n\n### Wiring via ncl\n\n`ncl` requires the **host service to be running** (it connects over a Unix socket):\n\n```bash\nncl messaging-groups create --channel-type <type> --platform-id \"<id>\" --name \"<name>\" [--is-group 1]\nncl wirings create --messaging-group-id <mg-id> --agent-group-id <ag-id> [--session-mode <mode>]\n```\n\nOmitted `engage_mode`/`engage_pattern`/`unknown_sender_policy` come from the adapter declaration for the right context (DM vs group). Run `ncl wirings help` / `ncl messaging-groups help` for the full flag list.\n\n### Threading override (`--threads`)\n\n`ncl wirings create/update ... --threads true|false` controls whether platform thread ids are honored for this wiring. `true` (in groups) means per-thread sessions and in-thread replies/typing/cards; `false` collapses to a flat session with top-level replies. Omitted = `NULL` = inherit the channel declaration. A wiring can *disable* threads on a threaded platform (Slack, Discord, GitHub), never enable them on a non-threaded one.\n\nTwo consequences to warn the user about:\n\n- **Session identity**: sessions are never deleted. Flipping `threads` on a live wiring orphans existing per-thread sessions (or splinters a shared one) — history stays in the old sessions; new messages start fresh ones.\n- **`mention-sticky` needs threads**: sticky engagement is keyed on per-thread session existence, so with resolved threads off it would engage once and never disengage. Creation and update coerce `mention-sticky` → `mention` (with a warning) when the effective thread policy is off.\n\n### Mention capability\n\nEach declaration states which mention signal the adapter emits: `platform` (real platform mentions), `dm-only` (only DMs are flagged), or `never`. On a `mentions: 'never'` channel (Linear OAuth apps, WhatsApp personal-number mode, Emacs), `mention`/`mention-sticky` wirings are **inert — they can never engage** — and `ncl` rejects them at create/update with an error citing the declaration. For groups on those channels, use a name pattern instead:\n\n```bash\nncl wirings update <id> --engage-mode pattern --engage-pattern '(?i)^@?<Name>\\b'\n```\n\n**Renaming an agent group does not update stored patterns.** Declared group patterns containing `{name}` are substituted with the agent group's name *at creation* and stored literally — after `ncl groups update <id> --name <NewName>`, audit that group's wirings for patterns still matching the old name and update them.\n\n## Wire New Channel\n\nFor each unwired channel:\n\n1. Read its SKILL.md `## Channel Info` for terminology, how-to-find-id, typical-use, and default-isolation\n2. Ask for the platform ID using the platform's terminology\n3. Ask the isolation question (see below)\n4. Register with the appropriate flags\n\n### Isolation Question\n\nPresent a multiple-choice with a contextual recommendation. The three options:\n\n- **Same conversation** (`--session-mode \"agent-shared\"` + existing folder) — all messages land in one session. Recommend for webhook + chat combos (GitHub + Slack).\n- **Same agent, separate conversations** (`--session-mode \"shared\"` + existing folder) — shared workspace/memory, independent threads. Recommend for same user across platforms.\n- **Separate agent** (new `--folder`) — full isolation. Recommend when different people are involved.\n\nUse the channel's `typical-use` and `default-isolation` fields to pick the recommendation. Offer to explain more if the user is unsure — reference `docs/isolation-model.md` for the detailed explanation.\n\n### Register Command\n\n```bash\npnpm exec tsx setup/index.ts --step register -- \\\n  --platform-id \"<id>\" --name \"<name>\" \\\n  --folder \"<folder>\" --channel \"<type>\" \\\n  --session-mode \"<shared|agent-shared|per-thread>\" \\\n  --assistant-name \"<name>\"\n```\n\nThe `register` step creates the agent group (reusing it if the folder already exists), the messaging group, and the wiring row. `createMessagingGroupAgent` auto-creates the companion `agent_destinations` row so the agent can address the channel by name.\n\nOmitted engage/policy fields default from the channel adapter's declaration (see \"Channel Defaults\" above). Optional overrides: `--trigger \"<regex>\"` (explicit engage pattern), `--engage-mode <pattern|mention|mention-sticky>`, `--is-group <true|false>`, `--unknown-sender-policy <strict|request_approval|public>`. Don't pick a mention mode on a channel whose declaration says `mentions: 'never'` — it can never engage there.\n\nNew agent groups are created on the instance default provider (`DEFAULT_AGENT_PROVIDER` in `.env`, or `claude` when unset). To run a group on a different provider, switch it after creation with `ncl groups config update --provider <name>` (e.g. `codex`).\n\nFor separate agents, also ask for a folder name and optionally a different assistant name.\n\n## Add Channel Group\n\nWhen adding another group/chat on an already-configured platform, open\n`.claude/skills/add-<channel>/SKILL.md`, follow its current group-discovery\ninstructions, ask the isolation question, then register. Channel-specific\nprocedures belong in that channel's skill, not here.\n\n## Change Wiring\n\n1. Show current wiring (agent_groups × messaging_group_agents)\n2. Ask which channel to move and to which agent group\n3. Delete the old `messaging_group_agents` entry, create a new one\n4. Note: existing sessions stay with the old agent group; new messages route to the new one. The `agent_destinations` row created for the old wiring is NOT automatically removed — if you want the old agent to stop seeing the channel as a named target, delete it from `agent_destinations` manually.\n\n## One-Time Check: Legacy Mis-Wired WhatsApp Groups\n\nInstalls that approved WhatsApp group registration cards before the channel-defaults model wired those groups as `engage_mode='pattern'`, `engage_pattern='.'` — respond-to-everything (the card flow couldn't tell groups from DMs on non-threaded platforms). Check once:\n\n```bash\npnpm exec tsx scripts/q.ts data/v2.db \"SELECT mga.id, mg.platform_id, mg.name FROM messaging_group_agents mga JOIN messaging_groups mg ON mg.id = mga.messaging_group_id WHERE mg.channel_type='whatsapp' AND mg.is_group=1 AND mga.engage_mode='pattern' AND mga.engage_pattern='.'\"\n```\n\nFor any hit the operator didn't deliberately configure as always-on, offer the repair options in `/add-whatsapp`'s \"Migration audit\" section (flip to mention/name-pattern engagement, or delete the wiring).\n\n## Show Configuration\n\nDisplay a readable summary showing:\n\n- **Agent groups** with their wired channels (from `messaging_group_agents`)\n- **Configured-but-unwired** channels (credentials present, no DB entities)\n- **Unconfigured** channels\n- **Privileged users**: `SELECT user_id, role, agent_group_id FROM user_roles ORDER BY role='owner' DESC`","author":"@nanocoai","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/nanocoai/nanoclaw/tree/main/.claude/skills/manage-channels","license":"MIT","category":"document","lang":"en","tokens":2338,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[],"requires":{"mcp":[],"tools":[]},"safety":{"flags":[],"scannedAt":"2026-08-22","hasScripts":false,"networkEndpoints":[]}}