开始使用

准备

• 电脑：macOS 或 Linux，装有 curl 和 openssl（大多数系统都有）。暂不支持 Windows。
• 服务器（可选）：Linux，x64 或 arm64，云主机即可。
• 手机：较新的浏览器即可，无需安装 App。
• Claude Code 或 Codex：在每台运行 Agent 的机器上安装并用你自己的账号登录。Ponte 使用你自己的订阅来驱动它们，本身不附带订阅。

在电脑上安装

在终端中运行：

• 它会把 ponte 可执行文件下载到 ~/.ponte/bin，只有发布者签名校验通过才会安装。
• 它会询问设备名和你的地址 https://<name>.ponte.sh——在任何地方打开面板都用这个地址。它会根据你的用户名建议一个名字；名字是公开的，可以改掉，也可以清空跳过，之后在面板里选。
• 它会把 Ponte 作为后台服务（launchd 或 systemd）启动，重启后会自动恢复，然后打开 http://localhost:23513 的面板，浏览器已自动登录，无需注册账号。
• 打开新的终端窗口即可使用 ponte 命令。ponte open 可以让这台电脑的浏览器重新登录。

首次设置

面板打开后会有一个简短的设置向导。每一步都可以跳过，之后都能在设置中修改。

• 语言和设备名。
• Agent：检查这台电脑上的 Claude Code 和 Codex（是否安装、版本是否够新、是否已登录），并告诉你缺什么。
• 权限：新会话如何处理工具调用。默认是直接运行工具，不询问：Agent 会自行修改文件、运行命令。选择先询问则每次工具调用都需要你批准。每个会话都可以单独修改。
• 通知：Agent 完成工作或需要你时发送通知。
• 地址：如果安装时跳过了，在这里选择你的 <name>.ponte.sh。
• 连接：添加服务器和手机（见下面两步）。首页会保留一份开始使用清单，列出尚未完成的步骤。

添加服务器

在设置向导中点添加服务器或另一台电脑（之后可以用侧边栏的二维码图标配对设备，或 ponte pair），会显示一条类似这样的加入命令：

• SSH 登录服务器，在那个会话里运行它——不要用 ssh host '…' 的方式，那样无法回答它的提问。安装过程相同，会询问服务器的名字。
• 如果服务器有公网 IP（大多数云主机都有），它还会询问是否允许你的其他设备通过互联网直接连接它（仍是端到端加密）。选择允许后，请在服务器防火墙或云平台安全组中放行入站 TCP 端口 23512；在此之前，你的设备会经由中继连接它。
• 服务器会打印一个确认码，你的电脑上会出现带确认码的加入请求。两边一致才批准。
• 配对后的设备彼此拥有完全控制权：Agent、终端和文件。只配对你自己的机器。设置 → 设备访问可以把某台设备设为仅接受控制：其他设备能控制它，它不能访问其他设备。
• 在使用 systemd 的 Linux 上，安装程序会启用 lingering，让 Ponte 在退出登录后继续运行。仅当安装程序提示时，才需要在服务器上运行 sudo loginctl enable-linger $USER；之后可用 ponte doctor 检查。
• 也可以在电脑上运行 ponte peer add --ssh user@host，它会通过 SSH 完成以上全部步骤（包括 lingering），执行前会先展示计划并征求确认。

添加手机

在设置向导中点添加手机（之后可以用设置 → 账户 → 登录手机，或在终端运行 ponte setup phone），会显示一个二维码。

• 用手机相机扫码并打开链接。手机会通过中继登录，全程端到端加密。
• 把页面添加到主屏幕（iPhone：分享 → 添加到主屏幕），从主屏幕打开并允许通知——需要你批准或工作完成时都会提醒你。
• 之后在任意浏览器打开 https://<name>.ponte.sh 即可，用通行密钥（在设置 → 账户中添加）或新的二维码登录。

日常使用

• 在任意设备上开启 Claude Code 或 Codex 会话，并选择它在哪台机器上运行——比如你的服务器。关掉页面或锁屏后它也会继续工作。
• 你在终端里开的会话也会出现在这里，可以在面板或手机上接着用。用 ponte codex 启动 Codex，其他设备就能向它发消息、停止它。
• 每台设备的终端和文件，在其他设备上点一下就能打开。
• 项目：给协调者一个目标，它会把工作分派给你各台机器上的会话，并用看板列出等你处理的事。
• ponte status 显示你的设备；ponte sessions list 列出所有设备上的会话。

更新

• 设备跟随稳定版渠道，每小时检查一次新版本：发布后一小时内，面板会提示更新，你的设备也会发通知。
• 一键安装——点立即更新，或在设置 → 更新中更新任意设备——也可以运行 ponte update。
• 每次更新安装前都会校验发布者签名。
• 如果新版本无法启动，设备会自动回滚到之前的版本。
• 除非你开启，更新不会自动安装：ponte update auto on 会在每天 05:00、没有会话运行时安装更新。
• 面板里的新功能和本站的更新日志，会列出每个版本的变化。

须知

• Agent 默认直接运行工具，不询问。如果想逐个批准，可以在设置向导或设置中改为先询问。
• Ponte 运行的会话会自己压缩上下文：超过 256k token 且空闲 55 分钟时（在提示词缓存过期之前），以及 Agent 主动要求时。每次压缩都是一次计入你账户的模型调用；可以在设置 → 上下文压缩中关闭。
• Agent 工作时，设备不会因空闲而休眠；可以在设置 → 通用 → 保持主机唤醒中修改。
• 安装时会在 ~/.claude/settings.json 中加入 hooks，并在你没有自行设置时写入 cleanupPeriodDays: 90——Claude Code 会保留 90 天的对话记录。ponte uninstall 会移除 hooks，保留这项设置。

Ponte 的服务能看到什么

你的对话、代码和文件都留在你自己的设备上，Ponte 也不发送任何统计或崩溃报告。少数服务能看到一些元数据：

• 中继。两台设备无法直连时，会经由 Ponte 的中继通信——目前只有一个中继：hk.relay.ponte.sh。你发送的内容是端到端加密的；中继能看到 IP 地址、数据大小和时间。
• 手机登录页面和 <name>.ponte.sh 也由它提供：你需要信任它如实提供这个页面。ponte setup 可以把你的设备改为使用你自建的中继。
• 名称服务。每台设备每 6 小时向 names.ponte.sh 查询一次自己持有的地址；它能看到设备的公钥和 IP 地址。
• 更新。每台设备每小时向 dl.ponte.sh 查询最新版本（失败时改用 npm），它能看到设备的 IP 地址。
• 仅在你开启时：可信 HTTPS 名称（ponte setup）会把你设备的 IP 地址（包括局域网地址）交给 dns.ponte.sh，并向 Let's Encrypt 申请证书；模型网关会从 usemagpie.ai 下载 Magpie。

卸载

在每台设备上运行：

$ ponte uninstall

$ ponte uninstall --purge  # 同时删除 ~/.ponte

• 它会等待仍在工作的会话结束（--force 不等待），然后停止守护进程，移除其 launchd 或 systemd 服务、终端、Claude Code hooks、shell 配置文件中的 PATH 行以及可执行文件。
• 它会保留 ~/.ponte（配置、设备身份、数据库、日志），重新安装后仍是同一台设备。--purge 会删除它。

遇到问题

• ponte doctor 检查安装、守护进程及其服务、终端和每个 Agent，并逐条给出修复方法。
• ponte open 让这台电脑的浏览器重新登录面板。
• ponte setup 修改设备名、直连和中继设置，或连接手机和其他设备。
• ponte status 显示它是否在运行、连接了哪些设备；ponte restart 重启它。
• 日志：~/.ponte/ponte.log，以及服务输出 ~/.ponte/daemon.log 和 ~/.ponte/daemon.err。