设备与 Agent
浏览器管理工作,开发机执行代码。
连接模型
连接器主动发起 HTTP 与 WebSocket 连接,开发机无需开放入站端口。浏览器和开发机必须都能访问工作台地址。跨设备时不要填写 localhost;公网使用 HTTPS / WSS。
设备在线只表示连接器可访问;Agent 能否运行取决于是否安装、登录及目标能力探测。仅运行工作台的服务器设备不会作为本地执行目标展示。
确认设备接入的空间
连接团队设备时,先在浏览器切换到目标团队,再生成部署命令。临时令牌绑定当前空间和成员;设备连接后不会跟随浏览器切换到其他空间。用个人用户名和密码登录连接器仍进入原账号空间。
设备会话不能管理或切换协作空间。需要变更接入空间时,停止原连接器,在目标空间重新生成部署命令;不要复用已绑定其他空间的状态目录。团队内仍执行设备归属与目录授权检查。详见团队设备接入。
连接器配置
| 配置 | 说明 |
|---|---|
| WORKBENCH_URL | 工作台地址;生产实例使用 HTTPS。 |
| WORKBENCH_USERNAME / WORKBENCH_PASSWORD | 个人账号凭据,用于原账号空间;团队请使用团队页面生成的部署命令。也可使用 WORKBENCH_TOKEN。 |
| CODEX_WORKSPACE_DIR | 默认工作目录,建议明确设置仓库绝对路径。 |
| WORKBENCH_DEVICE_NAME | 在工作台显示的设备名称。 |
| WORKBENCH_DEVICE_DIR | 可选的状态目录,绑定工作台、租户和账号。 |
| WORKBENCH_EXECUTE_CODEX=false | 关闭远端执行;此时可用 --once 单次同步。 |
| WORKBENCH_SYNC_EXCERPTS=false | 关闭摘要、结构化历史正文和图片预览同步。 |
Agent 探测与运行
默认通过 ACP 探测 Codex 和 Claude Code,分别在 PATH 中查找 codex-acp 和 claude-agent-acp。也可使用 ACP_CODEX_EXECUTABLE、ACP_CLAUDE_EXECUTABLE 显式指定路径。关闭 ACP 后,Codex 可使用原生 CLI / App Server 通道。
连接器使用当前用户的 Agent 安装和登录状态。Agent 历史解析器存在,不代表对应 Agent 已安装。模型目录与续聊能力按运行时返回值展示。
升级、断线与多实例
先更新工作台,再升级并重启连接器。设备页默认生成 macOS 常驻命令,重启电脑后登录桌面即可自动上线。常驻设备会话自动续期,连续 30 天未续期后需重新接入。“普通后台”模式可关闭终端,重启电脑或 24 小时会话到期后需重新接入。
使用 npx --yes agent-workbench-connector@latest --status 查看连接标识和日志路径,使用 npx --yes agent-workbench-connector@latest --stop <连接标识> 正常停止并移除该连接的常驻设置。普通后台命令可添加 --foreground,前台运行时按 Ctrl+C 退出。默认状态保存在 ~/.workflow-data/devices/,按服务器与账号隔离。升级包不会清除状态。
断线后保留未确认的回报并自动重连。设备会话过期后需在设备页面重新生成部署命令;配置文件登录方式仍可重新登录启动。迁移源码版连接器时保留原状态目录,不要启动两个进程处理同一设备。
pnpm add -g agent-workbench-connector
agent-workbench-connector --env-file ./agent.env