接入聊天通道

开始前

通道	连接方式	配置完成后
企业微信	API 模式 → 使用长连接	保存 Bot ID 和 Secret
飞书	事件订阅 → 使用长连接接收事件	发布新版本并完成管理员审核
Slack	Socket Mode	Install / Reinstall to Workspace

不需要公网 IP、域名或回调地址。同一个机器人只连接一台运行 Vinez 的机器。

1

企业微信（智能机器人）

企业微信客户端 → 工作台 → 智能机器人 → 创建机器人 → 手动创建 → API 模式 → 使用长连接。复制 Bot ID 与 Secret。

# ~/.vinez/config.yaml
wecom:
  bot_id: "你的 Bot ID"
  secret: "你的 Secret"     # 长连接专用，不是回调模式的 Token/EncodingAESKey
  bot_name: "vinez"        # 机器人在群里的 @名字，不含 @

保存配置并重启 Vinez。bot_name 必须与机器人的实际名称一致。建议直接私聊机器人派活；需要群内协作时，再在群里 @机器人。

2

飞书（自建应用）

飞书开放平台 → 创建企业自建应用 → 添加机器人能力 → 凭证与基础信息。复制 App ID 与 App Secret。事件订阅选择 使用长连接接收事件。

权限管理中申请以下权限：

权限	用途
`contact:user.employee_id:readonly`	获取成员 `user_id`
`im:message.p2p_msg:readonly`	接收私聊消息
`im:message.group_at_msg.include_bot:readonly`	接收群里 @机器人的消息
`im:message:readonly`	读取消息、附件和引用内容
`im:message:send_as_bot`	以应用身份发送与更新消息
`im:resource:upload`	发送图片（配对二维码）

也可以在权限管理 → 批量导入/导出权限中，清空输入框后整段粘贴以下 JSON 一次性开通：

{
  "scopes": {
    "tenant": [
      "contact:user.employee_id:readonly",
      "im:message.p2p_msg:readonly",
      "im:message.group_at_msg.include_bot:readonly",
      "im:message:readonly",
      "im:message:send_as_bot",
      "im:resource:upload"
    ],
    "user": []
  }
}

# ~/.vinez/config.yaml
feishu:
  app_id: "cli_xxxxxxxxxxxx"
  app_secret: "你的 App Secret"

发布新版本并等待企业管理员审核通过。保存配置并重启 Vinez。建议直接私聊机器人派活；需要群内协作时，再在群里 @机器人。

3

Slack（app + Socket Mode）

api.slack.com/apps → Create New App → From an app manifest。选择 Workspace，粘贴以下 Manifest：

display_information:
  name: vinez
  description: Team AI engineering execution center
features:
  bot_user:
    display_name: vinez
    always_online: true
  slash_commands:
    - command: /vinez
      description: "vinez: check tasks, list, stop, send feedback, pair app"
      usage_hint: "[help | list | status <id> | stop <id> | done <id> | fb <text> | bind]"
      should_escape: false
oauth_config:
  scopes:
    bot:
      - chat:write
      - im:write
      - im:history
      - channels:history
      - groups:history
      - files:read
      - files:write
settings:
  event_subscriptions:
    bot_events:
      - message.im
      - message.channels
      - message.groups
  socket_mode_enabled: true

Basic Information → App-Level Tokens：生成带 connections:write 的 xapp-…。OAuth & Permissions → Install to Workspace：复制 xoxb-…。

# ~/.vinez/config.yaml
slack:
  bot_token: "xoxb-..."   # OAuth & Permissions 页
  app_token: "xapp-..."   # App-Level Tokens，需 connections:write

保存配置并重启 Vinez。修改权限或斜杠命令后，执行 Reinstall to Workspace。建议直接私聊机器人派活；需要频道内协作时，先邀请机器人，再 @机器人。

常用命令：/vinez help、/vinez list、/vinez status 5、/vinez stop 5、/vinez fb 反馈内容、/vinez bind。

4

绑定同事的身份

Web 后台 → 用户 → 绑定身份。为每位使用者填写对应通道的成员 ID：

通道	填什么	去哪拿
企业微信	userid，形如 `ZhangSan`	企微管理后台的成员 UserID
飞书	`user_id`（不是 `open_id`），形如 `a1b2c3d4`	管理后台的用户信息
Slack	Member ID，`U` 开头	点头像 → 个人资料 → 右上 `⋮` → Copy member ID

排障

症状	处理
完全没反应，日志里也没有入站记录	在群聊中 @机器人；Slack 频道先邀请机器人；检查日志中是否出现“已连接”
消息收到了，但只回一句引导语	在 Web 后台绑定该用户的通道身份
Slack：加了权限还是报 `missing_scope`	执行 Reinstall to Workspace，再检查实际生效的权限
Slack：`/vinez` 打出来是「not a valid command」	重新导入 Manifest，并执行 Reinstall to Workspace
飞书：权限明明开了却不生效	发布新版本，并等待企业管理员审核通过
企微：原本好的，突然收不到消息了	将 API 模式改回“使用长连接”，并确认没有其他 Vinez 实例连接同一机器人

日志位置：~/.vinez/logs/vinezd.log。