Skip to content

绑定机器 ​

Bot 在成员自己的机器上运行。本页讲怎样把一台机器绑定到你的账号:最省事的是把一句话发给机器上的 Agent,让它自己装好、绑好;也可以用桌面端、命令行或 Docker。绑定后的日常管理见 我的机器与 Bot。

打开「绑定新机器」 ​

任选一个入口:

  • 头像菜单里的「绑定新机器」(还没搭过 Bot 的成员这里显示「接入我的电脑」);
  • 左侧导航栏「机器与 Bot」→ 机器列表底部的「绑定新机器」,还没有机器时是页面中间的「绑定新机器」按钮;
  • 首页欢迎页第一步「绑定新机器」→「开始绑定」,或侧栏「开始使用」卡片。

对话框打开时会自动生成一个一次性的接入码(形如 ABCD-EF23),30 分钟内有效,过期后自动换新。顶部步骤条显示进度:「复制给 Agent」→「机器接入」→「Bot 就绪」。

方式一:发给你的 Agent(推荐) ​

适用于 macOS 和 Linux,机器上已经装好并登录了 Claude Code、Codex 等任一 Agent。

发给你的 Agent

  1. 在对话框「发给你的 Agent」里点「复制」,复制那句话。它形如:
    text
    帮我接入共工空间:读取 https://gg.example.com/api/install.md 并按步骤执行,接入码 ABCD-EF23。
  2. 在要绑定的那台机器上打开 Claude Code、Codex 等,把这句话粘贴给它。
  3. 等它干完,通常 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 不会失败退出,而是改为请你在网页上确认:

  1. 终端(或 Agent 的回复)里会出现一个「确认链接」和 4 位「核对码」,并显示「等待确认…」。
  2. 如果「绑定新机器」对话框还开着,「机器接入申请」卡片会直接出现在对话框里,你也会收到一条通知;也可以用浏览器打开那个确认链接(页面标题「确认机器接入」)。
  3. 核对网页上的「核对码」与终端里的一致,确认「系统」「发起 IP」是你这台机器,点「允许接入」。
  4. 机器随即完成绑定,自动建好 Bot 并打开私聊。

只允许你自己刚发起的接入

「允许接入」后,这台机器归属于点允许的那个账号。只在你本人刚发起接入、且核对码与终端一致时允许;不认识的申请点「拒绝」。

确认申请 15 分钟内有效,过期后提示「接入申请已过期」,在机器上重新运行同一条命令即可。命令中途被打断时,重新运行同一条命令会接着等原来的申请。

方式二:其他方式 ​

展开对话框里的「其他方式」,分两步:

① 安装客户端 ​

页面会按你当前的系统推荐一个安装包,也可以在「选择系统」里换:

选项说明
macOS(Apple 芯片) / macOS(Intel)桌面客户端,自带 daemon,见 桌面端
Windows桌面客户端
Linux x86_64 / aarch64(命令行)命令行 gg,见 命令行安装

已经装好客户端,点「我已安装」跳过。

② 打开接入链接 ​

  • 桌面端:在要绑定的那台机器上点「在客户端中打开」,桌面端会带入接入链接;没有自动打开时点「复制接入链接」,粘贴到桌面端首次引导里。详见 桌面端首次引导。
  • 命令行:展开「使用命令行」,点复制按钮,在机器的终端里执行:
    bash
    gg login --server https://gg.example.com --code ABCD-EF23
    也可以把接入链接直接交给 gg login:
    bash
    gg login 'gonggong://bind?server=…&code=…'
    绑定成功后终端输出「绑定成功:本机已归属 王磊(…)」。然后让它常驻:
    bash
    gg service install
    也可以用 gg 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。

相关页面 ​

基于 Apache License 2.0 开源