如何远程访问CompozyOS：Gateway配对、设备授权与安全模型完整教程-平芜编程栈

如何远程访问CompozyOS：Gateway配对、设备授权与安全模型完整教程

【免费下载链接】compozyAn operating system for AI agents. Plug in the agent CLIs you already use (Claude Code, Codex, Gemini CLI, Cursor) and they become a team: they split the work, hand tasks to each other, run automated on jobs and loops, and share one project memory. You steer everything from the browser.项目地址: https://gitcode.com/gh_mirrors/co/compozy

CompozyOS 是一个为 AI Agent 打造的操作系统，你可以把 Claude Code、Codex、Gemini CLI 等常用 Agent CLI 接进来组成一支协作团队。那么问题来了：当你不在服务器前面时，如何远程访问 CompozyOS？答案是内置的 Gateway 远程访问网关——通过一次性的 Gateway 配对码完成设备授权后，你就能用浏览器或 CLI 从任何设备安全地驱动自己的 Agent 团队。本文将带你从零走通 Gateway 配对、设备授权全流程，并讲透背后的安全模型。

一、远程访问总览：Compozy Gateway 是什么

Compozy 的守护进程（daemon）内置了一个远程访问网关（Gateway）。默认情况下它只监听本机，打开后则可以按"层级（tier）"对外暴露服务：

私有层级（private）：仅你信任的网络内可访问，适合家庭或办公室内网远程。
公网层级（public）：面向互联网暴露操作界面，开启时需要你显式确认（consent），适合彻底离开本机的工作场景。

Gateway 的暴露策略由一套"暴露权威（Policy）"管理，负责规划（Plan）、切换（Transition）和对账（Reconcile）每个界面的对外状态，源码位于 internal/gateway/policy.go。

二、准备工作：启动 Compozy 守护进程

远程访问的前提是守护进程正在运行。启动后，你可以随时查看当前 Gateway 的暴露状态和已配对设备：

compozy gateway status

该命令会输出当前暴露层级、启用的界面（surface）以及所有已授权设备的列表。它的实现见 internal/cli/gateway_commands.go。

三、Gateway 配对：签发一次性配对码

远程设备接入的第一步是"配对"。在守护进程一侧生成配对码（pairing artifact）后，它会得到一个一次性、有时效的凭证：

有效期默认 5 分钟，过期自动失效；
一次性使用：兑换成功即作废，无法重放；
同时最多允许 32 个待兑换配对码，防止被批量滥用。

这些限制定义在 internal/gateway/device_service.go（defaultPairingTTL、defaultPairingLimit），配对码的"签发—兑换—作废"状态机实现在 internal/gateway/pairing.go。CLI 侧会把配对码原子写入本地凭据目录（文件权限 0600），相关逻辑见 internal/cli/gateway_pairing_artifact.go。

四、设备授权：用`compozy connect`建立远程连接

拿到配对码后，在远程设备上执行连接添加，把 Gateway 地址和配对码兑换成设备凭据：

compozy connect add <profile名> --pairing <配对码文件> --address https://<网关地址> --use

关键点：

兑换即授权：守护进程验证配对码有效后，为该设备签发长期凭据（dev_前缀），并生成唯一设备 ID；
凭据哈希存储：服务端只保存凭据的哈希值，验证时使用恒定时间比较，抵御时序侧信道攻击（见 internal/gateway/device_service.go 中的Authenticate）；
切换目标：用compozy connect use <profile名>把该远程连接设为默认目标，compozy connect use local切回本机。

连接管理命令的完整实现见 internal/cli/connect_commands.go，支持 add / list / use / remove / export / import / ssh 全套子命令。

五、安全模型：Compozy 远程访问凭什么可信

CompozyOS 的设备授权模型有几层纵深防御，这也是它敢把操作界面暴露到公网的底气：

安全机制	说明
一次性配对码	5 分钟时效 + 单次兑换，杜绝凭据转发
凭据哈希 + 恒定时间比较	泄露数据库也无法还原原始凭据
即时吊销	吊销设备时同步断开其所有活跃流，秒级生效
单次流票据	实时事件流使用 30 秒有效的一次性票据，防流劫持
变更门（mutation gate）	同一设备同一时刻只允许一个变更操作落地
private / public 分级	公网暴露需显式同意，最小化暴露面

其中"吊销即断流"的逻辑在RevokeDevice中：吊销提交后 5 秒内强制终止该设备的全部连接（见 internal/gateway/device_service.go）。

六、远程操作矩阵：哪些能远程、哪些只能本机

Compozy 对远程能力做了清晰的边界划分（gatewayOperationMatrix）：

✅可远程：会话（sessions）、任务读取、循环（loops）、记忆（memory）、设置、扩展管理、Gateway 自身管理；
❌仅本机：任务变更（task mutations）、任务队列与调度权限、Agent 内核、托管 MCP、资源变更。

💡 提示：仅本机操作建议通过 SSH 端口转发接入，compozy connect ssh可一键建立 SSH 通道（见 internal/cli/connect_ssh.go）。

七、设备管理三件套：列表、改名、吊销

配对之后，建议养成定期巡检的习惯：

compozy device list # 查看所有已配对设备 compozy device rename <id> --name "新名字" # 给设备起个好认的名字 compozy device revoke <id> # 吊销设备并断开其活跃流 compozy gateway audit # 审计 Gateway 安全态势

命令实现位于 internal/cli/device_commands.go。发现陌生设备？先吊销再排查，这是最稳妥的动作。

八、常见问题 FAQ

Q1：配对码过期了怎么办？重新在守护进程侧生成一个新的配对码即可，旧码永远不会复活。

Q2：换了一台新设备，需要重新配对吗？需要。每台设备各自持有独立凭据，互不共享，一台被吊销不影响其他设备。

Q3：为什么远程不能执行任务变更？任务调度和 Agent 内核被刻意保留在本机层级，保证核心执行链始终由你信任的本地守护进程掌控，远程只负责"看"与"控"（会话、循环、设置等）。

📎 更多资料：Gateway 完整源码见 internal/gateway/，CLI 连接与凭据管理见 internal/cli/，设计与发布文档见 docs/。按照本教程完成配对后，你就可以在任何地方用浏览器远程指挥你的 AI Agent 团队了。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

如何远程访问CompozyOS：Gateway配对、设备授权与安全模型完整教程