绑定机器
Bot 在成员自己的机器上运行。本页讲怎样把一台机器绑定到你的账号:最省事的是把一句话发给机器上的 Agent,让它自己装好、绑好;也可以用桌面端、命令行或 Docker。绑定后的日常管理见 我的机器与 Bot。
打开「绑定新机器」
任选一个入口:
- 头像菜单里的「绑定新机器」(还没搭过 Bot 的成员这里显示「接入我的电脑」);
- 左侧导航栏「机器与 Bot」→ 机器列表底部的「绑定新机器」,还没有机器时是页面中间的「绑定新机器」按钮;
- 首页欢迎页第一步「绑定新机器」→「开始绑定」,或侧栏「开始使用」卡片。
对话框打开时会自动生成一个一次性的接入码(形如 ABCD-EF23),30 分钟内有效,过期后自动换新。顶部步骤条显示进度:「复制给 Agent」→「机器接入」→「Bot 就绪」。
方式一:发给你的 Agent(推荐)
适用于 macOS 和 Linux,机器上已经装好并登录了 Claude Code、Codex 等任一 Agent。

- 在对话框「发给你的 Agent」里点「复制」,复制那句话。它形如:text
帮我接入共工空间:读取 https://gg.example.com/api/install.md 并按步骤执行,接入码 ABCD-EF23。 - 在要绑定的那台机器上打开 Claude Code、Codex 等,把这句话粘贴给它。
- 等它干完,通常 1–3 分钟。对话框显示「等待接入…Agent 会自己下载安装,通常 1–3 分钟」。
Agent 会按服务器给出的步骤自己完成:
- 下载
gg、校验 sha256,安装到~/.local/bin/gg(只装在你的主目录里,不用 sudo,不改系统设置); - 用接入码把机器绑定到你的账号;
- 用它自己这种 Agent 建好一个 Bot(名字是「你的名字的 Agent 名」,如「王磊的 Claude Code」),并建好你和它的私聊;
- 执行
gg service install,让gg在后台常驻、登录后自动启动(macOS 用 launchd,Linux 用 systemd 用户服务); - 最后运行
gg status,输出里同时有bound: yes和service: running才算接好。
接好后,网页会自动关闭对话框并打开和新 Bot 的私聊,直接说需求即可。
TIP
- 机器已经绑定过别的服务器时,Agent 会停下来问你,不会擅自改动
~/.gonggong。 - Linux 上想在注销登录后仍保持在线,按提示执行
loginctl enable-linger。 ~/.local/bin不在 PATH 里时,用~/.local/bin/gg运行命令。- Windows 不支持这种方式,请展开「其他方式」用桌面客户端。
接入码过期了也没关系
Agent 用到的接入码已过期或已用过时,gg 不会失败退出,而是改为请你在网页上确认:
- 终端(或 Agent 的回复)里会出现一个「确认链接」和 4 位「核对码」,并显示「等待确认…」。
- 如果「绑定新机器」对话框还开着,「机器接入申请」卡片会直接出现在对话框里,你也会收到一条通知;也可以用浏览器打开那个确认链接(页面标题「确认机器接入」)。
- 核对网页上的「核对码」与终端里的一致,确认「系统」「发起 IP」是你这台机器,点「允许接入」。
- 机器随即完成绑定,自动建好 Bot 并打开私聊。
只允许你自己刚发起的接入
「允许接入」后,这台机器归属于点允许的那个账号。只在你本人刚发起接入、且核对码与终端一致时允许;不认识的申请点「拒绝」。
确认申请 15 分钟内有效,过期后提示「接入申请已过期」,在机器上重新运行同一条命令即可。命令中途被打断时,重新运行同一条命令会接着等原来的申请。
方式二:其他方式
展开对话框里的「其他方式」,分两步:
① 安装客户端
页面会按你当前的系统推荐一个安装包,也可以在「选择系统」里换:
| 选项 | 说明 |
|---|---|
| macOS(Apple 芯片) / macOS(Intel) | 桌面客户端,自带 daemon,见 桌面端 |
| Windows | 桌面客户端 |
| Linux x86_64 / aarch64(命令行) | 命令行 gg,见 命令行安装 |
已经装好客户端,点「我已安装」跳过。
② 打开接入链接
- 桌面端:在要绑定的那台机器上点「在客户端中打开」,桌面端会带入接入链接;没有自动打开时点「复制接入链接」,粘贴到桌面端首次引导里。详见 桌面端首次引导。
- 命令行:展开「使用命令行」,点复制按钮,在机器的终端里执行:bash也可以把接入链接直接交给
gg login --server https://gg.example.com --code ABCD-EF23gg login:bash绑定成功后终端输出「绑定成功:本机已归属 王磊(…)」。然后让它常驻:gg login 'gonggong://bind?server=…&code=…'bash也可以用gg service installgg run在前台运行(关掉终端就会离线)。加上--create-bot claude等参数,gg login会像方式一一样顺便建好 Bot 和私聊。 - Docker:展开「在 Docker 中运行」,复制那行
GONGGONG_BIND_URL='…',加到服务器docker/daemon目录的.env(另需GG_VERSION与GONGGONG_MACHINE_ID),运行docker compose up -d --build,容器首次启动时自动绑定。完整步骤见 Docker 部署。
用这些方式绑定成功后,对话框显示「绑定成功」并列出这台机器上检测到的 Agent 及版本。点「新建 Bot」在这台机器上建 Bot(见 创建 Bot),或点「稍后」。
服务器地址与证书
- 非本机的服务器必须用
https://地址,http://只允许localhost这类本机地址。 - 服务器用自签证书时,
gg login需要加--fingerprint <SHA-256 指纹>;用私有 CA 时加--ca-file <CA 证书路径>。详见 HTTPS 与证书。
绑定后上报什么
绑定后这台机器归属于你。客户端会上报机器名、系统、CPU、内存,以及这台机器可用的 Agent(Claude Code、Codex、Gemini CLI、CodeBuddy、pi、DeepSeek Harness、Antigravity CLI)。Agent 的登录信息、供应商和 API Key 都只保存在机器上,不会上传,见 Agent 工具与供应商。
常见报错
WARNING
- 「接入链接尝试次数过多,已锁定,请稍后在 Web 端重新生成」:同一网络短时间内失败太多次,等 10 分钟后再试。
- 「待确认的接入申请过多,请稍后再试」:同一个人同时最多 3 个待确认的申请,先在网页上处理掉。
- 「接入申请已被拒绝」:网页上点了「拒绝」,需要时重新运行接入命令。
- 「无法连接服务器 …」:检查这台机器能否访问服务器地址(防火墙、端口、内网/VPN)。
- 「只允许通过 https:// 连接非本机服务器」:把地址改成
https://。
多台机器与重新绑定
一个账号可以绑定多台机器(比如办公室的 Mac 和一台 Linux 云主机),每台各绑一次。创建 Bot 时选择它在哪台机器上运行。
- 同一台机器重新绑定:恢复原来的机器记录和上面的 Bot,网页显示「已恢复原有机器」。
- 机器换主人:这台机器之前归属别人、且上面还有他的 Bot 时,绑定会被拒绝,需要原主人先删除这些 Bot。
- 暂时下线:停掉
gg run、执行gg service uninstall或退出桌面端即可。在机器上执行gg logout会删除本机凭据,以后再gg login会恢复这台机器及其 Bot。 - 彻底不用了:在网页上吊销机器,见 我的机器与 Bot。