初始化

初始化你的设备，将其连接到 Pontia Cloud，然后打开 Remote Dashboard，开始与你的 Agent 协作。需要引导式设置时选择交互式向导；当 Agent 或脚本需要明确执行每一步时，使用独立命令。

请先查看安装要求，并安装你要使用的 Agent Client。以将要运行这些客户端的操作系统用户身份执行设置。本地服务管理需要运行 systemd 用户服务管理器的 Linux，或 macOS 13.5 及更高版本。

交互式初始化

在已安装 Node.js 和 npm 的情况下，运行：

npx @pontia/cli init

该命令会在需要时安装 Pontia 并启动向导。如果 Pontia 已在你的 PATH 中，也可以直接运行 pontia init。

向导可以让你：

选择要安装的 Client 集成：pi、Codex、Claude Agent 或其任意组合。Codex 包括其守护进程启动和启动器。
检查并确认设置。
创建或保留本地 API token，启动 Pontia 服务，并启用所选 Client。
登录 Pontia Cloud，并为远程访问注册设备。

当提示登录并启用远程访问时，选择接受并完成浏览器授权。选择一个可用的 Edge 并确认设备名称。设置成功后，Pontia 会打开 Remote Dashboard。按照 Dashboard 指南开始你的第一个 Session。

现有配置和 Workspace Browser 根目录会被保留。未配置根目录时，Workspace Browser 默认使用你的主目录。

之后配置或修复 Client

运行 pontia setup 选择 Client，或直接指定一个：

pontia setup pi
pontia setup codex
pontia setup claude-agent

每个命令都会应用推荐的本地配置并检查安装。现有的有效配置会被复用，缺失的集成文件会被恢复。Pontia 服务启动后，所选 Client 会被启用。

所选 Client 的运行时路径会为 Pontia 服务保存。显式设置的环境路径优先于已保存的路径。服务配置变更时服务会重启。对于 Codex，之后请打开新终端，或运行打印出的 shell 激活命令。

非交互式初始化

按顺序执行以下步骤，包括链接中适用于你平台的说明。每一步都包含命令以及继续前需要检查的结果。

Client 认证和 Cloud 登录可能需要用户授权。出现提示时完成授权，然后继续设置。

1. 准备安装

选择要启用的 Client（pi、Codex、Claude Agent 或其组合）、设备显示名称以及要浏览的项目目录。所有步骤都以同一个操作系统用户身份运行。按照 Agent Client 中的说明启用 ACP Agent。

使用 npx @pontia/cli install 安装 pontia 和 pontiad，并将 $HOME/.local/bin 添加到 PATH；或者使用 shell 安装脚本，但不运行交互式初始化程序。对于缺失的 Client 工具，请参考官方的 pi 快速开始、tmux 安装指南或 Codex CLI 安装。只安装所选 Client 及其前置依赖；复用已能正常工作的安装。
为所有命令选定一个绝对路径的 PONTIA_HOME。保留现有安装的配置和凭据。默认值为 ~/.pontia。
对于 Codex，选择其已认证的现有主目录：已配置的 CODEX_HOME，默认为 ~/.codex。Codex 认证、其守护进程和 Pontia 都使用同一个目录。

使用默认路径，或保留 shell 中已设置的路径：

export PONTIA_HOME="${PONTIA_HOME:-$HOME/.pontia}"
pontia --version

如果使用 Codex，还需设置：

export CODEX_HOME="${CODEX_HOME:-$HOME/.codex}"

在设置过程中使用的每个 shell 中都使用这些环境变量值。在下面的示例中替换为你的实际路径和 ID。

2. 安装并验证 Client 集成

在这一步安装并启用所选 Client 的集成。

只运行所选 Client 对应的命令：

pontia setup pi
pontia setup codex
pontia setup claude-agent

pi 需要已安装 pi；其设置会安装 @pontia/pi-client-plugin。Codex 需要已安装支持守护进程的 CLI；其设置会配置自动启动、验证连接，并安装启动器和 shell PATH。Claude Agent 需要 Node.js LTS；设置会在缺失时安装默认 host，并检查现有或显式选择的 host。

这些命令会保存运行时路径、配置 Pontia 服务并启用所选 Client。对于 Codex，请打开新终端或运行打印出的激活命令。使用每个 Client 自己的登录流程完成认证；设置不会登录，也不会更改模型凭据、沙箱设置或审批策略。

3. 配置并启动本地服务

将监听地址、Workspace Browser 根目录和 Client 可执行文件设置合并到 $PONTIA_HOME/config.toml 中，并保留你想保留的现有设置。可用选项见配置。

每个命令都使用同一个绝对路径的 PONTIA_HOME。将持久的服务设置保存在 config.toml 中。

pontia up
pontia status

pontia up 会在 config.toml 中创建或保留 API token，安装或刷新按用户运行的服务，等待其进入健康状态，并打印 Local Dashboard URL。如果服务已在运行，它会重启服务。打印出的 URL 包含本地 API token，请妥善保管。

4. 校准 Client 设置

现在列出可用的 Client 条目：

pontia client list --json

结果是包含 agent_clients 数组的 JSON。通过 client_type 找到每个所选条目，并检查其 effective_config。确认 tui_command 指向 Pontia 服务可用的可执行文件。

如果需要覆盖可执行文件，请编写一个包含所需 config_overrides 的 JSON 文件，并保留现有值。例如：

{"tui_command": "/absolute/path/to/client"}

将其应用到列表中该条目的 id：

pontia client set --id <CLIENT_ID> --config <JSON_FILE>

在文件中使用原始的 pi 或 Codex 可执行文件路径，然后检查 effective_config 是否反映了该更改。

再次运行 pontia client list，确认每个所选条目都显示 enabled。第 7 步会通过从 Remote Dashboard 启动 Session 来验证这些 Client。

5. 登录 Pontia Cloud

登录以授权向 Pontia Cloud 注册设备：

pontia login

打开打印出的验证 URL，登录并批准一次性代码。授权成功后命令即完成。当 Agent 执行设置时，它可以在等待批准期间把 URL 和代码分享给你。

你可以复用现有的有效 Cloud 登录；下一步中的 pontia remote edges 会确认访问权限。请妥善保管保存在 auth.json 中的凭据。

6. 无提示注册设备

列出已登录用户可用的 Edge：

pontia remote edges

该命令输出一个由包含 id 和 name 字段的对象组成的 JSON 数组。选择一个可用的 Edge，并将其 ID 与设备名称一起传入：

pontia remote enable --edge <EDGE_ID> --name "Development workstation"
pontia doctor

将 <EDGE_ID> 替换为列表中的某个 ID，并同时提供 --edge 和 --name 以进行非交互式注册。

注册会创建设备身份并更新正在运行的本地服务。已注册的设备会保留其现有名称和 Edge。如需重命名，请使用 pontia remote edit --name "New name"。

7. 验证已连接 Cloud 的设备

运行：

pontia status
pontia client list
pontia doctor

确认以下结果：

本地服务正在运行，HTTP 健康检查状态正常。
每个所选 Client 条目都已启用。
诊断报告确认设备已注册，且本地加密身份匹配。

打开 pontia doctor 给出的 Remote Dashboard URL。按照 Dashboard 指南激活一个 Workspace，并用每个所选 Client 启动一个 Session。Session 成功启动即说明设备可访问，且 Client 已可使用。

对于由 Agent 协助的设置，最后应汇总已配置的 Client、服务健康状态、设备名称、Remote Dashboard URL 和验证结果。如果还需要在浏览器中验证，请附上 URL 和上述步骤，以便你完成验证。如需帮助，请参阅远程访问和故障排除。