mvanhorn/agentcookie

agentcookie – 将 Chrome Cookie 从 Mac 同步到 Linux 代理

功能说明

• 持续监控 macOS 上的 Chrome Cookies SQLite 文件，利用 macOS Keychain 进行解密，并通过加密的 Tailscale 通道将变更传输到运行自动化代理的 Linux 机器。
• 在 Linux 端，Cookie 会通过 Chrome DevTools Protocol (CDP) 实时注入到 Chrome 的内存存储中，因此任何使用 Puppeteer、Playwright 或原始 CDP 连接的脚本，都能看到与您 Mac 上相同的登录会话。
• 无需手动复制粘贴 Cookie 字符串，无需额外的登录步骤，也无需重写 Linux 机器上 Chrome 的磁盘 SQLite 数据库。

为何重要

• 许多 AI/自动化代理（例如 Grok Bot、自定义机器人、爬虫工具）都在无头 Linux VM 上运行。它们通常需要在您桌面已登录的网站上以已登录用户的身份操作。agentcookie 以安全且无人值守的方式自动化了此桥接过程。
• 使用 AES-256-GCM 加密以及通过 Tailscale 配对仪式生成的点对点密钥，确保只有指定的接收端能读取 Cookie。
• 处理 macOS 特有的保护机制（Keychain、Chrome 的应用绑定加密）作为源端，并利用 CDP 在接收端进行安全注入。

运作方式（高阶流程）

1. 源端 (macOS) – agentcookie source --watch 监控 Chrome Cookies 文件，以只读方式读取，使用 Keychain 解密，应用可配置的 Cookie 策略，将数据封装在密封信封中，并通过 Tailscale 网络上的 HTTPS 传输。
2. 接收端 (Linux) – agentcookie sink 在 Tailscale 地址上监听，解密信封，重新应用其策略，并调用 Storage.setCookies 通过 CDP 将 Cookie 放入 Chrome 的实时存储中。
3. 实时 CDP 注入 – Linux 端无需重写 SQLite；Cookie 会立即出现在任何新标签页或无头浏览器环境中。

关键组件

• 配对向导 – 生成一次性代码和 URL；双方通过 Tailscale tailnet 交换公钥。
• 策略文件 – blocklist.yaml（Linux 默认为空，表示不传输任何内容）或 allowlist.yaml，用于限制同步哪些域名。
• 配置 – 位于 ~/.config/agentcookie/ 下的 YAML 文件，用于源端、接收端及可选的多接收端设置。
• CLI 命令 – wizard install、pair、source、sink、doctor、status。

典型设置

1. 在 Mac 和 Linux 上安装二进制文件（或使用 go install）。
2. 在 Mac 上运行源端向导，记下配对代码。
3. 在 Linux 机器上创建接收端配置（或在 macOS 接收端上使用向导）并使用代码配对。
4. 在 Linux 上以 --remote-debugging-port=9223 启动 Chrome（或让向导检测现有实例）。
5. 运行 agentcookie sink（或 systemd 用户服务）并观察同步过程。

安全性注意事项

• 通讯采用端到端加密；Tailscale WireGuard 通道增加了另一层保护。
• Linux 接收端默认使用空白黑名单，因此除非您明确允许，否则不会传输任何内容。
• Google/Workspace 使用的设备绑定会话凭证 (DBSC) 在接收端仅在短时间内有效；您仍需在 Linux Chrome 上登录一次 Google。
• 明文侧边文件 (~/.agentcookie/cookies-plain.db) 以未加密方式存储 Cookie – 请将其视为临时缓存；主要的安全性保证在于实时 CDP 注入。

限制

• 仅支持单向同步 (Mac → Linux)。未实现反向同步。
• DBSC 保护的 Cookie 在接收端过期很快；必须在本地重新验证。
• 尚未支持实时密钥轮换 – 您必须重新运行向导以生成新密钥。
• 支持多接收端扇出，但每个接收端都会收到完整的 Cookie 集，因此需要信任机制。

深入了解

• 架构细节：docs/architecture.md
• 线路格式规范：docs/protocol.md
• 威胁模型：docs/threat-model.md
• 快速入门指南：docs/quickstart.md

许可 – MIT。

---

agentcookie 是一个实用的工具，适合任何在无头 Linux 机器上运行自动化代理，且希望在不进行手动 Cookie 处理的情况下复用现有 Chrome 登录状态的用户，同时确保数据加密并仅限于其私人 Tailscale 网络上的机器。