vwork cloud · 控制台

在线设备

设备	租户	状态	企微	企业 / 企微账号	最后心跳	实例(api_port)	版本

设备入网入网令牌只显示一次；设备首次启动自动注册

租户	前缀	备注	已用/上限	到期	状态

Agent 版本 / 灰度升级升级包是 zip，需包含 start_now.py；设备下载后校验 sha256，重启替换

版本	大小	SHA256	创建	备注

% 在线设备

升级记录

设备重连并上报新版本后自动变 applied

时间	设备	租户	目标版本	状态	信息

下发指令 （预设 84 个）

全选设备

原始 JSON（可手工修改，会覆盖表单字段）

最近下发 点「重发」会把这台设备+这条指令重新填回上面

时间	设备	请求	结果	耗时

任务中心按设备逐个发送，自动节流；支持 {name} 变量

间隔 ~ 秒日限额

任务列表

ID	名称	设备	状态	进度	成功/失败	计划

受众 / 通讯录 从设备同步好友、群、标签；勾选后加入任务

	user_id	名称	备注	类型	设备

群

群 ID	名称	人数

标签

标签 ID	名称	组

同步任务

时间	类型	设备	状态	数量	错误

素材库上传后由设备下载到本机再发送

图片/视频/文件上限 UPLOAD_MAX_MB（默认 64MB）；删除只删记录，不删已落盘文件。

预览	名称	类型	大小	租户	创建

实时事件来自 /v1/events（企业微信收到的消息）

第三方 API Key

允许危险指令

授权设备（不选＝本租户全部设备）：

名称	前缀	租户	授权设备	危险指令	状态	创建

第三方调用：POST /open/v1/call，Header X-API-Key: vw_xxx
该 Key 只能操作「本租户 + 授权设备」；用 GET /open/v1/devices 拿授权设备列表。调非授权设备返回 403 device_not_allowed，跨租户返回 403 device_not_in_tenant。

API 调用手册 给第三方开发者看的，照着粘就能跑

0. 认证

Header:  X-API-Key: vw_xxxxxxxx
Base:    http://<本机IP>:8090
说明:    每个 Key 只能操作「本租户 + 授权设备」，越权返回 403

1. 获取授权设备列表

GET /open/v1/devices
X-API-Key: vw_xxx

→ {"ok":true,"devices":[{"device_id":"DESKTOP-M8BCDC8","online":true,
   "dll":true,"wecom_login":true,
   "corp_name":"锅圈食品（上海）股份有限公司","corp_short_name":"锅圈",
   "wecom_user":"顾继威","dept_name":"江苏加盟伙伴",
   "instances":[{"api_port":8989,"listen_port":9000}]}]}

2. 下发指令（万能接口，84 条 type 都走这里）

POST /open/v1/call
Content-Type: application/json
X-API-Key: vw_xxx

{"device_id":"DESKTOP-M8BCDC8",
 "api":{"type":1000},
 "instance":8989,
 "timeout":20}

→ {"ok":true,"result":{"data":{"status":1},"errmsg":"OK","errno":0},"ms":23}

3. 发送文本（最常用，单独封装）

POST /open/v1/send_text
{"device_id":"DESKTOP-M8BCDC8","user_id":"FILEASSIST","msg":"你好"}

→ {"ok":true,"result":{"data":null,"errmsg":"OK","errno":0},"ms":132}

4. 订阅消息事件（SSE 长连接）

GET /open/v1/events
X-API-Key: vw_xxx

data: {"event":"device.message","device_id":"DESKTOP-M8BCDC8",
       "ts":1792874442107,
       "data":{"type":100,"msg_type":2,"content":"你好",
               "user_id":"7881300686911617","is_self_msg":0}}
data: {"event":"device.message",...,"data":{"type":200,"nick_name":"三水君","msg":"加一下"}}
data: {"event":"device.message",...,"data":{"type":100,"msg_type":14,
       "content":{"image_url":"/media/3585....jpg","size":514681}}}

5. 健康检查

GET /open/v1/health
→ {"ok":true,"gateway":{"ok":true,"devices":1}}

错误码

HTTP	回包	含义 / 处理
401	`invalid_api_key`	Key 错/被禁用
403	`device_not_allowed` + `allowed`	该 Key 没授权这台设备
404	`device_offline`	设备没连上来（agent 没开/断网）
504	`timeout`	指令发出去了，20 秒没回（DLL 卡住/崩了）
200	`device_result_ok:false`	设备收到了但执行失败，看 `errno/errmsg`
200	`{"blocked":true}`	本地校验拦下（缺必填参数/未知 type）
200	`errno:-1 未登录执行失败`	企业微信没登录

常用 type（完整 84 条见「控制台」预设）

type	功能	必填参数
1000	获取登录状态	—
1001	刷新并获取登录二维码	path
1002	获取个人信息	—
2000/2001	好友列表（外部/内部）	page_num, page_size
2002	群列表	page_num, page_size
2003	群成员列表	chat_room_id
3000	发送文本	user_id, msg
3001/3003/3004	发送图片/文件/视频	user_id, path
3008	发送卡片链接	user_id, title, desc, target_url, cover_url
3009	群聊@指定成员	chat_room_id, at_list, msg
4000	加好友（群成员）	chat_room_id, user_id, msg
4002	同意好友请求	user_id, corp_id
5000/5001	建群（外部/内部）	name, user_id_list
5003	发群公告	chat_room_id, content
5007	获取群二维码	chat_room_id, path

注意事项

文档里标 int 的必须传数字（传 "1" 会报「参数错误」）；数组传 JSON 数组
同一个 Key 可以并发调用，网关按 cmd_id 匹配回包，不会串
图片消息的 content 是对象，带 image_url，直接拼 base + image_url 就能看
设备离线时指令会立刻 404，别重试太猛，建议 5 秒一次
机器可读版：GET /open/v1/docs

命令日志

时间	来源	租户	设备	请求	结果	耗时

设备令牌签发 / 轮换 / 吊销（令牌只显示一次）

同时吊销旧令牌

换机或令牌泄露时点「吊销」，设备会立刻被断开并禁止重连。

设备	租户	令牌前缀	标签	创建	到期	状态

审计日志登录 / 指令 / Key / 令牌 / 用户操作

时间	操作者	角色	租户	动作	对象	详情	IP	结果

用户平台运营 / 租户管理员 / 只读

用户名	角色	租户	状态	创建

告警设备离线 / DLL / 掉登录 / 指令失败率 / gateway

时间	类型	租户	设备	消息	状态	次数	确认

用量 / 配额

租户套餐 / 状态 / 用量

租户	名称	套餐	状态	设备	消息	存储