teamwiseflow awada-channel-setup
背景
awada extension 是专为对外 crew（如 sales-cs）打造的消息通道，可令 sales-cs 以 企业微信联系人的形态连接外部用户。配置默认直接启用 customerDB hook（自动记录客户 来访、更新状态），因此整个配置过程是一个可机械执行的 SOP。
何时使用
- 用户或 main agent 要求启用 sales-cs / 任何对外 crew → 建议配置 awada channel
- 用户明确要求绑定/修复 awada channel
SOP（按顺序执行）
1. 确认 awada 依赖已就位（通常已预装，跳过）
awada 走 relay 网关 HTTP/WS 传输，运行时依赖 ws + zod，已在以下场景预装，正常无需手动操作：
- Docker 部署：镜像 build 时已
npm install --omit=dev进/opt/openclaw/awada/node_modules - 源码部署：
apply-addons.sh已自动装进<PROJECT_ROOT>/awada/node_modules（哈希守卫，幂等）
仅当 node_modules 被清理、package.json 变更、或日志报 Cannot find module 'ws'（plugin=awada）时，才手动补装：
cd <WISEFLOW_PROJECT_ROOT>/awada && pnpm install --prod
工作目录 = <WISEFLOW_PROJECT_ROOT>/awada/（单层结构）。
2. 写 openclaw.json
读取同目录 openclaw-awada-sample.json 拿到最小配置片段，然后用本技能脚本把它
合并进运行中的 ~/.openclaw/openclaw.json：
awada-channel-setup
脚本行为：
- 读
openclaw-awada-sample.json作为模板 - 提示输入
awadaKey（必填）；lane可选（留空 = 服务器默认User）；relayBaseUrl缺省时回退到官方 relay 域名https://relay.openclaw-for-business.com - 合并进
~/.openclaw/openclaw.json的channels.awada与plugins（customerDB hook 默认enabled: true，agentId=sales-cs） - 原子写回（temp + os.replace），先备份
.bak-<ts> - 不重启 Gateway（由步骤 3 人工确认）
awadaKey由 relay admin 签发（须含awada:lane:<laneId>scope），与签名用的OFB_KEY是两份独立凭证。lane在 relay 侧 provision 时已绑死 platform，客户端不发platform。客户端不持 Redis 凭据。客户端最小配置只需awadaKey。
3. 建议重启 Gateway
改 binding/channel 路由后必须完整重启（hot-reload 不重置 routing 缓存，见 it-engineer MEMORY「binding routing 坑 2」）：
重启会断所有 session，执行前必须告知用户并征得同意。
按部署方式二选一：
- Docker 部署（容器内 IT engineer 检测到
/.dockerenv存在）：告知宿主用户执行docker restart <容器名>（容器内无法自重启自身）。 - 源码部署（systemd）：
systemctl --user restart openclaw-gateway.service。
4. 验证
- Channel 状态显示 connected
- 用外部账号给 sales-cs 发一条消息，确认收发闭环
- customerDB：
~/.openclaw/workspace-sales-cs/db/出现新来访记录
排障检查单
Cannot find module 'ws'→ 步骤 1 预装未就位（Docker 镜像 build 漏装 / 源码部署 apply-addons.sh 没跑）；手动cd <PROJECT_ROOT>/awada && pnpm install --prod补装- 网关连接失败 / 401 → 检查
relayBaseUrl可达性 +awadaKey是否含awada:lane:<lane>scope - awada-server（relay 侧）进程存活 + Redis 连通性（relay 内部，客户端不直接碰）
- webhook 回调地址与平台后台一致
channels.awada的lane（若配）与 relay 侧 provision 的 lane 一致；不配则 server 默认User（platform 由 lane 绑定，客户端不配）- binding 写了但消息仍走 default agent → 见 it-engineer MEMORY「binding routing 坑 1」：
binding 必须写
accountId（通配用"*"）