AgentFlow
AGENTFLOW DOCUMENTATION

设备与 Agent

浏览器管理工作,开发机执行代码。

连接模型

浏览器 / 手机→工作台服务←开发机连接器 → 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/,按服务器与账号隔离。升级包不会清除状态。

断线后保留未确认的回报并自动重连。设备会话过期后需在设备页面重新生成部署命令;配置文件登录方式仍可重新登录启动。迁移源码版连接器时保留原状态目录,不要启动两个进程处理同一设备。

bash
pnpm add -g agent-workbench-connector
agent-workbench-connector --env-file ./agent.env