# Awada Channel Setup

> 启用并配置 awada channel，使对外 crew（如 sales-cs）能以企业微信联系人的形态 连接外部用户。当用户或 main agent 要求启用 sales-cs 时使用本技能：建议配置 awada channel → 获得确认 → 按 SOP 完成安装依赖、写 openclaw.json、重启 Gateway。

- Skill: `teamwiseflow/awada-channel-setup` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add teamwiseflow/awada-channel-setup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/teamwiseflow/awada-channel-setup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: teamwiseflow (https://skillmd.com/u/teamwiseflow)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/teamwiseflow/awada-channel-setup

---


# 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）时，才手动补装：

```bash
cd <WISEFLOW_PROJECT_ROOT>/awada && pnpm install --prod
```

工作目录 = `<WISEFLOW_PROJECT_ROOT>/awada/`（单层结构）。

### 2. 写 openclaw.json

读取同目录 `openclaw-awada-sample.json` 拿到最小配置片段，然后用本技能脚本把它
合并进运行中的 `~/.openclaw/openclaw.json`：

```bash
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/` 出现新来访记录

## 排障检查单

1. `Cannot find module 'ws'` → 步骤 1 预装未就位（Docker 镜像 build 漏装 / 源码部署 apply-addons.sh 没跑）；手动 `cd <PROJECT_ROOT>/awada && pnpm install --prod` 补装
2. 网关连接失败 / 401 → 检查 `relayBaseUrl` 可达性 + `awadaKey` 是否含 `awada:lane:<lane>` scope
3. awada-server（relay 侧）进程存活 + Redis 连通性（relay 内部，客户端不直接碰）
4. webhook 回调地址与平台后台一致
5. `channels.awada` 的 `lane`（若配）与 relay 侧 provision 的 lane 一致；不配则 server 默认 `User`（platform 由 lane 绑定，客户端不配）
6. binding 写了但消息仍走 default agent → 见 it-engineer MEMORY「binding routing 坑 1」：
   binding 必须写 `accountId`（通配用 `"*"`）