桌面应用
桌面应用程序集成了图形聊天界面、本地 agent-wechat Hub 节点以及 wx 命令行工具。独立 npm CLI 依然保持单独维护。
-
从 GitHub Releases 下载适合你平台的应用安装包。
平台系统 下载格式 安装方式 macOS (Apple Silicon) .dmg将 AgentWechat 拖入“应用程序”文件夹。 Windows x64 或 ARM64 对应架构的 -setup.exe为当前用户运行安装程序。 Ubuntu 24.04 x64 或 ARM64 .deb使用系统软件包管理器安装。 -
打开 AgentWechat,选择 使用当前设备 (Use this device) 启动本地 Hub,或者选择 连接到其他 Hub (Connect to another hub) 输入节点地址及访问密钥。
-
添加微信 Profile 并按照提示完成登录。
-
打开 设置 (Settings) 配置网络访问权限、安装全局
wx命令,或导出访问密钥供其他客户端使用。
该应用在当前用户权限下运行,使用系统原生凭据管理和文件对话框;网络访问权限和开机自启均为可选配置。如果需要允许外部局域网设备连接,可能需要在系统防火墙中放行相应端口。
连接命令行工具 (CLI)
桌面端的访问密钥保存在系统的安全密钥环(Keyring)中。独立的 CLI 安装则使用受保护的文件凭据:
wx config servers add desktop --url http://127.0.0.1:6174 --token-file /path/to/exported-keywx --server-name desktop status状态返回信息中将包含该 Hub 及其 Native 后端详情。如果修改了桌面端监听端口,请使用实际显示的地址。
开启局域网或远程访问
网络访问采用 HTTPS 协议。桌面端会自动生成自签名证书,无需手动提供 TLS 证书文件。独立的 wx serve 同样支持 --tls-cert-file 与 --tls-key-file,方便接入已有证书(例如为局域网主机名签发的证书)。受公共信任的 HTTPS 地址(包括 Tailscale Serve 等)无需额外配置证书。若 Hub 使用自签名私有证书,可从该 Hub 的桌面端设置中复制证书内容,并在客户端桌面端的 高级 (Advanced) → 私有证书 (Private certificate,可选) 中粘贴配置。浏览器会遵循系统证书信任规则,而 CLI 可以在单次调用中显式指定受信任证书:
wx --server-name desktop --ca-cert-file /path/to/certificate.pem status在配置远程连接时,请将对应的 HTTPS 地址保存为服务器 URL。
通过地址打开指定视图
Web 客户端为每个视图提供了独立的 URL 路径,因此刷新、后退与书签都能保留当前位置。会话、消息和图片均使用经过 URL 编码的 ID 命名。请在这些路径前加上 #:
| 打开目标 | 路径 |
|---|---|
| 账号列表 | /{server}/accounts |
| 会话列表 | /{server}/{account}/chats |
| 指定会话 | /{server}/{account}/chats/{chat} |
| 高亮显示指定消息 | /{server}/{account}/chats/{chat}/message/{message} |
| 图片或视频查看器 | /{server}/{account}/chats/{chat}/media/{message} |
| 会话或群聊详情 | /{server}/{account}/chats/{chat}/info |
| 通讯录、发起新聊天、设置 | /{server}/{account}/contacts, /new-chat, /settings |
{server} 为 Hub 的服务器 ID;可直接从浏览器地址栏中复制它与账号 ID。若该账号已登出,应用会展示登录界面并在登录成功后跳转到目标地址。若未找到对应会话或消息,应用会打开会话列表或聊天界面并进行提示。
消息通知
点击消息通知可直接定位并打开该消息所在的会话。在 macOS 上:
- 通知中心会按会话对通知进行分组折叠,在应用中打开会话会自动清除该会话的所有通知。
- 标记已读 (Mark as Read) 会将该会话标记为已读并清除通知。若此后收到了更新的消息,该会话仍将保持未读。
- 回复 (Reply) 会将输入的文本作为对该消息的引用回复发出,并随后将该会话标记为已读。该操作仅在消息支持被引用时显示。
- 应用重启后,点击通知仍可正常打开对应的会话。
若未弹出通知,请前往 系统设置 → 通知 中允许 AgentWechat 发送通知。