leepokai/Codync · 上手攻略

  • 仓库：leepokai/Codync
  • 链接：https://github.com/leepokai/Codync
  • 分类：agent（主分类：agent，副分类：skill）
  • 作者：Jay
  • 更新：2026-10-30

资料来源：GitHub README（2026-10-30 抓取）、docs/README.md（索引自检日期 2026-10-19）。版本号以 README 当前描述为准，具体 release tag 以 GitHub Releases 为准。

是什么

Codync 是一个 开源的"把本机编码 Agent 变成手机可聊的机器人"的调度层。它自己不含模型，也不托管你的账号，而是把你电脑上已经装好、已经登录的编码 Agent（Claude Code、Codex、Cursor、Gemini CLI、Copilot、OpenCode、Pi、Grok Build 等约 40+ 个，走 ACP registry）包装成一个个"有名有姓的 Bot"，让你用 iPhone、Mac、Windows、Linux 桌面或终端直接给它们派活。

架构上分三层：

  • codync-host：一个 Rust 单二进制守护进程，跑在你的电脑上。它用 ACP 协议驱动各个 Agent、用 SQLite 保存对话记录、对本机提供 HTTP/SSE API，并负责推送通知与用量统计。Linux 上是静态二进制（x86_64 + arm64），任何发行版都能跑。
  • 客户端：iPhone 原生 SwiftUI App（iOS 26+，App Store 免费）；Mac / Windows / Linux 一个 Electron 桌面 App（菜单栏/托盘 + 聊天窗口）；终端 UI codync-host tui（SSH 友好）。
  • 中继：官方托管的 Cloudflare Relay 免费提供，端到端加密，手机与电脑之间只转发密文；同一 Wi-Fi 或 Tailscale 下会直连而不经过中继。

一个 Bot 的属性包括：名字、角色头像、常驻指令、Agent 后端、项目目录、权限策略，每个 Bot 有一条持久会话，底层 Agent 会话用 session/load 续跑，也可以 New session 重开。多个 Bot 可放进群聊，被 @ 到的 Bot 依次作答，最多 3 轮；Bot 之间也能互相求助（内置 team MCP server）。

许可：代码 Apache 2.0；⚠️ 2.11.0 及之前版本是 MIT。名称、Logo 与 Codync Cloud 中继不在授权范围内；自建/多租户服务需自建 relay 与账号（见 TRADEMARK.md）。

解决什么问题

  1. 手机端"指挥电脑干活"的路径太长。原生 App 是"找对工作会话 → 再挑环境"，两步。Codync 的模型是"我已经知道该把活派给谁"：打开聊天、说人话、放下手机，完成后收到通知。
  2. 多 Agent 并行管理。每个 Bot 绑定自己的 Agent、项目目录和审批策略，可以并排跑，互不干扰。
  3. 跨设备访问自家电脑。不用 Tailscale、不用 VPN、不做端口转发；账号本身不解锁任何一台电脑，每台电脑自己批准每台设备。
  4. 权限审批要人确认，但人不在电脑前。Bot 发起的编辑会变成"审批卡片"推到手机；本地 loopback 脚本用的 codync-host send 永远不会替你批准，超时也只是打印摘要到 stderr。
  5. CLI 化的 Agent 编排。codync-host send --bot reviewer --wait --json "..." 可以塞进 CI 或脚本，拿到机器可读的结果 JSON。

快速安装

macOS / Linux 一行安装（README 称 macOS 上会装 App、host 打包在 App 里；Linux 会装 host，有图形会话时另装 AppImage 桌面端）：

curl -fsSL https://raw.githubusercontent.com/leepokai/Codync/main/packaging/install.sh | sh
# 服务器 / 无头 Mac：加 --host-only
curl -fsSL https://raw.githubusercontent.com/leepokai/Codync/main/packaging/install.sh | sh -s -- --host-only

其他平台：

# macOS：Homebrew cask
brew install --cask leepokai/codync/codync
# 或下载 codync-macos.dmg 拖入 Applications
# Linux：仅 host
brew install leepokai/codync/codync-host
codync-host install   # systemd --user 服务
codync-host pair     # 终端里出配对二维码
  • Windows：下载 codync-windows-x64.exe 运行，按当前用户安装，登录时自启 host。⚠️ Windows 安装包尚未做代码签名，SmartScreen 会拦一次，选"更多信息 → 仍要运行"。
  • iPhone：App Store 搜 Codync（iOS 26+，免费），扫桌面端 "Pair iPhone…" 的二维码。
  • 桌面端源码：cd apps/desktop && npm ci && npm run dev；host 测试 cd host && cargo test。

前置条件：装好并登录你要用的 Agent。Claude Code / Codex / Pi 通过 ACP adapter 走 npx 拉取，需要本机有 Node.js。

核心用法

日常命令速查（均来自 README 的命令表）：

codync-host install / uninstall    # 后台服务（macOS launchd / Linux systemd --user / Windows 登录 Run 键）
codync-host status                  # 装了吗？跑起来了吗？
codync-host pair [--json]           # 配对二维码 / 链接
codync-host tui [--url … --token …] # 终端里跟 Bot 说话（默认本机，适合 SSH）
codync-host serve [--port 19222]    # 前台运行
codync-host reset-token             # 轮换本地 loopback bearer token
codync-host cloud [--assistants on|off]   # 云开关 / URL / 状态；是否允许 ChatGPT、Claude 等接入
codync-host network                 # codync-network：多台电脑的网络（create/invite/join/status/promote/remove/recover）
codync-host devices                 # 列出 / 吊销已授权的远程设备
codync-host access                  # 审阅设备访问申请
codync-host statusline [-- <your command>]  # 包一层 Claude Code 状态栏命令

非交互式派活，脚本里最常用的一条：

codync-host send --bot reviewer --wait --json "Review the current diff without modifying files."

要点：

  • --bot 接受 Bot 的 ID 或精确的名字（大小写不敏感）；重名必须用 ID。
  • 正文可位置参数，也可 --file request.txt（--file - 读 stdin，UTF-8）。
  • --wait 会等最终回复（多段回复会合并打印）；不带 --wait 只打印被接受消息的 id/seq/turn。群聊不支持 --wait。
  • --reply-to <id> 引用某条历史消息；id 取自之前 --json 结果的 entryId 或 replyId。
  • --timeout 默认 1800 秒活跃秒；等待审批时计时暂停，超时不会批准请求也不会中止 Bot。
  • --json 输出字段包含 botId、entryId、entrySeq、turn、status（completed / failed / timeout）、可选 stopReason、reply、replyId、notices、elapsedSeconds、waitedForApprovalSeconds。
  • 退出码：0 = 完成或已接受；1 = 被停止/限额/拒绝/失败；2 = 参数非法或 Bot 缺失/歧义或对群聊用了 --wait；3 = host 不可用或 API 被拒；4 = 超时。

数据与端口：数据在 ~/.codync；本地 bearer token 授权 loopback 助手与 SSH 转发来的调用者。换端口或数据目录用 --port 和 CODYNC_HOME；开发构建默认端口 19223、数据目录 ~/.codync-dev。

典型适用场景

  • 通勤路上给 Claude Code 派活：出门前在电脑上起一个会话，到地铁上用手机说"把 README 的安装段翻译成英文"，回来手机上直接点批准。
  • 多角色评审流水线：一个 Bot 跑 Codex 改代码，另一个 Bot 跑 Claude 做 review，通过群聊或"让 Reviewer 看看这些改动"触发协作。
  • 多机器统一入口：Mac、Linux 台式机、云服务器都跑 host，登录后在手机上看到全部电脑的 Bot；SSH 机器也能被桌面 App 触达。
  • CI / 脚本化：用 codync-host send --wait --json 把审查任务派给指定 Bot，拿结构化结论。

坑与注意

  1. 现象：iPhone App 明明在 App Store 更新了，功能却还是旧的。影响：手机端与桌面端版本不同步，某些新功能要等 1 天以上。修复：每次 iPhone 发版都要过 App Review，通常 1 天或更久；桌面端会检测到"需要更新但手机端还没上"并等待，iPhone 端也会提示有新版——不是 bug，是审核时延。
  2. 现象：Windows 上 SmartScreen 报警。影响：用户以为安装包有毒。修复：当前 Windows 安装包未签名，信任来源后选"仍要运行"；macOS 版是已签名 + 公证的。
  3. 现象：send --wait 超时了。影响：以为任务失败，其实可能正卡在等审批。修复：超时不会替你批准也不中止 Bot，超时会打印审批摘要到 stderr；用 --json 的 waitedForApprovalSeconds 判断时间花在审批上。
  4. 现象：脚本里群聊用了 --wait。影响：退出码 2，命令直接失败。修复：群聊逐个回复的语义无法用单次等待表达，别在群聊上等。
  5. 现象：升级后配置"丢了"。影响：Bot、对话、计算机身份丢失。修复：升级前务必完全退出 Codync 再重开（下载的更新可能仍在等旧进程退出）；仍失败就卸载重装最新版本；macOS 上替换 Codync.app 前先停掉旧的 host 服务。不要用 Reset all data、清理工具或 brew --zap——保留 ~/.codync 与 Codync 的设置目录。
  6. 现象：更新失败反复重试。影响：版本卡住不前进。修复：卸载 App 后从 Releases 重装最新版；macOS 上先移除旧 host 服务。
  7. 现象：找不到某个 Agent。影响：只能用已装的那几个。修复：host 会从登录 shell 注入 PATH（另加 Homebrew、~/.local/bin、nvm、bun、volta、asdf、mise、pnpm 等）自动发现已装 Agent，并优先用其原生 ACP 模式；ACP registry 里的其余 Agent 首次使用时会自动拉取（npx / uvx / 带校验和的二进制）——这条路径需要网络和 Node.js。
  8. 现象：以为 Codync 会用你的账号去调厂商 API。影响：安全模型误判。修复：官方定位是"绝不拿你的登录态调 API"，Bot 跑的是你本机已登录的 Agent，额度上限来自本机 Agent（Claude 走 claude -p /usage 等本地命令，不触发模型调用）；Cursor 例外，会用本地保存的登录态向 cursor.com 查询额度。
  9. 现象：Windows 上某些功能不存在。影响：功能对不上。修复：远端屏幕、端侧语音、Claude Code 状态栏 hook 在 Windows 尚未支持。
  10. 现象：以为托管中继能读你的消息。影响：隐私误判。修复：中继只转发手机与电脑之间的密文；通知正文用手机密钥封装，push 中继看不到内容；同网或 Tailscale 下走直连。

与同类对比

  • Grok Bot / Muse / Dots：这几款是托管商业产品，绑定单一模型与订阅；Codync 自称是它们的开源替代，同样有命名 Bot、群聊、引用回复、Bot 互问、审批卡片、每 Bot 记忆、远端屏幕、语音通话、"需要你 / 完成"通知，但跑在你自己电脑上、可接任意编码 Agent、Apache 2.0 免费。
  • 纯 SSH + tmux：最省事的路子，但没法用手机的推送、审批卡片、群聊与多 Bot 编排；Codync 补的正是这一层。
  • 自建 Tailscale + 脚本：网络层等价，但要自己写 Agent 驱动、会话持久化与通知；Codync 把这些打包好。
  • 各 Agent 自带手机端：如果只用 Claude Code 且已有官方移动端，需求可能不成立；Codync 的差异在于"多 Agent + 群聊 + 跨电脑"。

一句话推荐结论

如果你想在手机上把本机已经付费登录的编码 Agent 当成同事一样派活，且拒绝再订阅一个聊天机器人服务，Codync 值得装——它把 ACP 生态、持久会话、审批与推送的脏活一次做完了；代价是你得自己维护本机 Agent 环境、接受"主机常开"的前提，以及 Windows 端尚未签名的粗糙感。

⚠️ 待核项：本文基于 README 与 docs 索引文本，未拉取 Releases 页确认当前最新 release tag 与 codync-host --version；官方文档明确写着"文档描述的是检出的实现，功能被文档记录不等于线上服务已验证"。文档索引自检日期为 2026-10-19，晚于它的改动未覆盖。