首次引导
本页介绍桌面端第一次打开时的绑定流程:把接入链接交给桌面端、核对服务器、点「绑定」。
本机还没有绑定时,打开桌面端会直接进入「绑定到团队服务器」页面。

第一步:在网页上拿到接入链接
- 用浏览器登录共工空间网页,打开「绑定新机器」(头像菜单,或左侧「机器与 Bot」里的「绑定新机器」)。
- 展开「其他方式」,已装好桌面端就点「我已安装」跳过下载。
- 在「② 打开接入链接」里二选一:
- 点「在客户端中打开」:浏览器会唤起桌面端,接入链接自动填进输入框。
- 点「复制接入链接」:切回桌面端,粘贴到「接入链接」输入框。
网页对话框的完整说明见 绑定机器。
自动填入
引导页打开时,以及每次从浏览器切回桌面端窗口时,如果输入框是空的,桌面端会读取剪贴板;剪贴板里是有效的接入链接或 gg login 命令就自动填入。
第二步:填入并核对
「接入链接」输入框接受以下任一种内容(前后的空格和引号会被忽略):
- 接入链接,形如
gonggong://bind?server=…&code=… - 网页「使用命令行」下复制的命令,如
gg login --server https://gg.example.com --code ABCD-EF23,或gg login 'gonggong://bind?…'
识别成功后,下方会列出解析结果:
| 项目 | 说明 |
|---|---|
| 服务器 | 要绑定的团队服务器地址 |
| 接入代码 | 一次性接入码,格式 XXXX-XXXX |
内容无法识别时,输入框下方会给出原因,例如「无法识别:请粘贴接入链接或 gg login 命令」「不是共工空间的接入链接」。
请确认这是你们团队的服务器,再点「绑定」。桌面端不会自动绑定,即使是通过链接唤起的,也必须你亲手点「绑定」。
服务器地址与证书
- 非本机的服务器必须用
https://地址;http://只允许localhost、127.0.0.1这类本机地址。 - 服务器用受信任的证书时不需要额外操作。用自签证书时,在命令后加
--fingerprint <证书指纹>(或在接入链接末尾加&fp=<证书指纹>)再粘贴进来,详见 HTTPS 与证书。
第三步:完成
点「绑定」后,桌面端会用接入码换取本机的长期凭据并启动 daemon。成功后:
- 进入主界面,右上角显示「已连接 服务器地址」。
- 在 macOS 上,如果屏幕录制、辅助功能还没有授权,会接着弹出「授予系统权限」页面。这两项只影响实时画面和远程操作,可以先点「稍后」,详见 权限与系统设置。
- 回到网页,「绑定新机器」对话框显示「绑定成功」并列出本机检测到的 Agent,点「新建 Bot」即可在这台机器上 创建 Bot。
常见问题
提示「接入链接已失效(已过期或已被使用),请在 Web 端重新生成」? 接入码 30 分钟内有效且只能用一次。回到网页重新打开「绑定新机器」,拿新的接入链接再绑。
提示「接入链接尝试次数过多,已锁定」? 稍后在网页上重新生成接入链接。
打开接入链接时提示「本机已绑定到 …,请先在设置中解绑」? 这台机器已经绑定过。要换绑到其他服务器或账号,先在「设置」里点「解除绑定…」,再重新打开链接。
之前用 gg login 绑定过? 桌面端和命令行共用同一份绑定信息,打开桌面端会直接进入主界面,不会出现首次引导。