| name | wire-nanoclaw-channel |
| description | Use when wiring any messaging channel to a NanoClaw agent group, or diagnosing adapter failures. Covers channel adapter install, routing wire (messaging_groups / messaging_group_agents / agent_destinations), push credentials bootstrap, and delivery verification. Common pitfalls: SDK peer dep split, withRetry timeout misread, credentials missing before adapter factory runs. |
Wire a Channel to NanoClaw
核心原则：channel wiring 链路 6 段，每段都有真凭据（真 log 行 + 真回执 id）。每段不通就停下来 debug，不跳过。
Use When
- 给 NanoClaw 接一个新 channel（任何 add-* skill）
- channel 装好但 agent 推不出去，按本 skill 反查每一段
- 诊断 adapter 未启动 / routing 未 wire / push 失败
整体链路·6 段闭环
┌─ 段 1 ── Pre-flight: .env / NanoClaw 服务 ──────────────┐
│ │
└──→ 段 2: 装 <channel> adapter（channels branch） ┘
↓
段 3: <channel> 认证（QR / OAuth / API key）
↓
段 4: wire routing（messaging_groups / mga / destinations）
↓
段 5: 建立 push 凭据（用户主动发一条，激活协议）
↓
段 6: 真推验证·log + platformMsgId + 手机真收
任何段失败，不要跳段，按 ## Recognition Scenarios 反查。
段 1·Pre-flight
cat .env
pnpm dev
段 2·装 channel adapter
git fetch origin channels
git show origin/channels:src/channels/<channel>.ts > src/channels/<channel>.ts
grep -q "import './<channel>.js';" src/channels/index.ts || \
echo "import './<channel>.js';" >> src/channels/index.ts
pnpm install <package>
pnpm run build
echo "<CHANNEL>_ENABLED=true" >> .env && cp .env data/env/env
pkill -f "tsx src/index.ts"; sleep 2; pnpm dev
段 3·Channel 认证
grep -iE "<channel>.*(adapter ready|login complete|resumed)" logs/nanoclaw.log | tail -1
ls data/<channel>/ 2>&1 | grep -E "auth|token|session"
段 4·Wire Routing
3 张表缺一不可：messaging_groups · messaging_group_agents · agent_destinations
情况 A: 普通用户主动发消息 → 系统自动建 messaging_group（无需手动 SQL）
情况 B（operator 自测，不自动建组）: 必须手动 wire（见下方 SQL）
情况 C: 通过 add- skill 提供的工具自动 wire（推荐）
TS=$(date +%s)
sqlite3 data/v2.db <<SQL
INSERT INTO messaging_groups
(id,channel_type,platform_id,name,is_group,unknown_sender_policy,created_at)
VALUES ('mg-${CHANNEL}-${USER}-${TS}','${CHANNEL_TYPE}','${PLATFORM_ID}',
'${USER} DM',0,'public',datetime('now'));
INSERT INTO messaging_group_agents
(id,messaging_group_id,agent_group_id,session_mode,priority,created_at,
engage_mode,engage_pattern,sender_scope,ignored_message_policy)
VALUES ('mga-${CHANNEL}-${USER}-${TS}',
'mg-${CHANNEL}-${USER}-${TS}','${AGENT_GROUP_ID}',
'shared',10,datetime('now'),'pattern','.','all','drop');
INSERT INTO agent_destinations
(agent_group_id,local_name,target_type,target_id,created_at)
VALUES ('${AGENT_GROUP_ID}','${CHANNEL}-${USER}','channel',
'mg-${CHANNEL}-${USER}-${TS}',datetime('now'));
SELECT COUNT(*) FROM messaging_groups mg
JOIN messaging_group_agents mga ON mga.messaging_group_id = mg.id
WHERE mg.channel_type = '${CHANNEL_TYPE}';
SQL
段 5·Push 凭据 Bootstrap
先收后推：重启后 push 凭据失效，用户必须主动从该 channel 发一条消息刷新。
grep "<channel> inbound" logs/nanoclaw.log | tail -3
段 6·真推验证
三件套，缺一不算真推：
grep "Message delivered.*channelType=<channel>.*platformMsgId" logs/nanoclaw.log | tail -3
grep -iE "<channel>.*deliver failed" logs/nanoclaw.log | tail -3 || echo "no failures"
Recognition Scenarios
RC-01 · pre-flight 文件不完整
症状：src/channels/<channel>.ts 不存在，但 .claude/skills/add-<channel>/SKILL.md 存在。
诊断：ls src/channels/<channel>.ts 2>&1
修复：git show origin/channels:src/channels/<channel>.ts > src/channels/<channel>.ts
RC-02 · SDK peer dep 版本分裂
症状：pnpm run build 报 TS2322；pnpm list 有两个 chat 版本共存。
诊断：pnpm list chat --depth=0
修复：pin chat 到与 adapter 精确相同版本，然后 pnpm install。
RC-03 · withRetry 假挂住
症状：adapter 启动 log 出现 attempt 1 (1s delay), attempt 2 (2s delay)...，服务看似挂住。
诊断：grep -E "attempt [0-9]+.*Error" logs/nanoclaw.log | tail -5（贴出输出）
修复：若见 ResourceNotFoundError → 检查 .env 凭据；若见 NetworkError → 检查网络；不要重启。
RC-04 · operator DM 不自动建组
症状：log 有 inbound，但 messaging_groups 表 0 行，wire-dm.ts 报 "No unwired groups"。
修复：参见段 4 情况 B，手动 INSERT 3 张表（messaging_groups / messaging_group_agents / agent_destinations）。
RC-05 · push 凭据失效
症状：outbound 有消息但 deliver failed，报 "No context_token for user" 或等价错误。
修复：让用户从该 channel 主动发一条消息，刷新 push 凭据（先收后推）。
RC-06 · outbound DB 有行 ≠ 真推
症状：outbound.db 有 channel 消息行，但手机没收到。
诊断：grep "Message delivered.*platformMsgId" logs/nanoclaw.log
修复：三件套验证（log Message delivered + platformMsgId 字段 + 手机真收）。Claude 必须贴出 platformMsgId=<具体ID>（如 platformMsgId=849234501）·不接受"已收到"敷衍。
RC-07 · 无 "Channel adapter started" log
症状：按 add-* SKILL.md 步骤完成，log 没出现 Channel adapter started · channel=<x>。
诊断：grep -i "adapter started\|adapter null" logs/nanoclaw.log
修复：确认 .env 有真实 credentials（非 placeholder）；无 credentials 时 adapter factory 静默返回 null。
Common Mistakes
| CM | 错误做法 | 正确做法 |
|---|
| CM-01 | .claude/skills/add-<channel>/SKILL.md 存在就认为模块已装 | 必须检查 src/channels/<channel>.ts 是否真实存在；skill ≠ 模块 |
| CM-02 | pnpm install <adapter> 成功就认为依赖对齐 | 必须 pnpm list chat 确认只有 1 个 chat 版本；版本分裂让 TypeScript 静默失败 |
| CM-03 | outbound.db 有消息行就认为推送成功 | 见 RC-06 三件套验证 |
| CM-04 | retry log 出现就认为网络问题，重启服务 | 见 RC-03 retry 诊断 |
| CM-05 | operator 本人给 bot 发消息期望自动建组 | operator DM 被识别为"bot 自聊"，不建组；必须手动 SQL INSERT 3 张表 |
Out of Scope
以下内容由各专属 skill 维护，不属于本 skill 范围：
ANTHROPIC_BASE_URL / OneCLI hostPattern 配置 → setup/ 或 init-oneclicontext_token 字段存储格式和失效时间 → add-wechat SKILL.md- withRetry 全错误重试的具体时长 →
add-telegram SKILL.md
- 各 channel credentials 获取流程 → 各
add-* SKILL.md
- 非 channel wiring 工作流问题（HARD-GATE、subagent 进程数）→
superpowers:* skills
自检：bash .claude/skills/wire-nanoclaw-channel/sanity-check.sh <channel>
