从安装到第一次对话。From install to your first conversation.

同机使用，打开 App 即可。Same machine: just open the app.

此流程仅适用于官网 macOS 直装版 CodeAfar，不适用于 TestFlight。App 使用随包附带的本机连接组件，直接复用当前系统用户的 Codex CLI、Codex Desktop 所带 CLI 或 Claude Code 的配置与历史；无需另装 CodeAfar CLI。

This path is for the direct-download macOS CodeAfar, not TestFlight. Its bundled local connector reuses the current OS user's Codex CLI, Codex Desktop bundled CLI, or Claude Code configuration and history. No separate CodeAfar CLI install is required.

1. 1
   确认 Codex 或 Claude 可在终端运行Run Codex or Claude successfully in Terminal
2. 2
   安装并打开 CodeAfarInstall and open CodeAfar

   从官网下载 ZIP，解压后将 CodeAfar.app 拖入“应用程序”，再打开。首次从旧的 CodeAfar Desktop 升级时，先结束本机任务并退出旧版，再安装 CodeAfar。打开确认原有配置与会话正常后，可将旧的应用包移到废纸篓；不要删除用户数据。之后检测到新版本时，侧边栏 CodeAfar 右侧才会出现更新按钮，点击后按提示下载、验证并重启。未发送的草稿或正在执行的本机任务会阻止重启。安装包已使用 Developer ID 签名并通过 Apple 公证。侧边栏会出现带 LOCAL 标记的本机 Host。

   Download the ZIP from the official site, extract it, drag CodeAfar.app into Applications, then open it. For the first upgrade from CodeAfar Desktop, finish local tasks, quit it, and install CodeAfar. Verify your existing configuration and sessions before moving the old application bundle to Trash; do not delete user data. Future updates appear as a button beside CodeAfar in the sidebar only when a newer version is available. Follow its prompts to download, verify and restart. Unsent drafts or running local tasks prevent restart. The download is Developer ID signed and notarized by Apple. A Host marked LOCAL appears in the sidebar.

3. 3
   选择工作区并创建 SessionSelect a workspace and create a session

   模型与受支持的选项来自本机 Provider。已有历史按 Provider 分组。若未检测到，前往 Settings → AI providers → Rescan；自定义 CLI 路径和非默认配置目录需要使用相同的 Provider 运行环境。

   Models and supported options come from the local provider. Existing history is grouped by provider. If detection fails, use Settings → AI providers → Rescan. Custom executables and data directories must use the same provider environment.

只在远程 Host 上安装。Install only on a remote Host.

在保存项目并运行 Codex CLI 或 Claude Code 的电脑上执行安装命令。本机 Desktop 模式不需要安装 CodeAfar CLI。

Run the installer on the computer that stores the project and runs Codex CLI or Claude Code. Local Desktop mode does not need CodeAfar CLI.

明确开放监听与文件范围。Explicitly enable listening and file access.

先完成远程 Host 安装，并以运行服务的同一系统用户验证 Codex 或 Claude 能正常回复。若已运行 codeafar setup，以下是对应的手动配置命令，无需重复更改已设置的权限。

Complete Host installation and verify a provider response as the same OS user running the service. If you used codeafar setup, the following are equivalent manual commands; do not change already configured permissions unnecessarily.

旧测试版迁移到新官网Move an older test build to the new domain

CodeAfar 官网与下载服务已统一为 codeafar.com，原测试域名已停用。如果旧版 CLI 的更新失败，在运行 Host 的电脑上执行以下一次性命令：

The website and downloads now use codeafar.com. The former test domain is retired. If an older CLI cannot update, run this one-time command on the Host computer:

这是旧测试域名和旧签名链的一次性迁移：安装器校验 beta.22 的 SHA-256，保留原有配对、目录授权与会话数据；如果运行中的托管服务属于当前配置，安装器会在任务结束后刷新并重启它。使用自定义数据目录时同时设置原有的 CODEAFAR_DATA_DIR。迁移后直接运行 codeafar update。新安装仍使用上方安装命令。

This is a one-time migration from the retired test domain and release key: the installer verifies beta.22's SHA-256 and preserves pairings, workspace access, and session data. If the managed service belongs to this configuration, it is refreshed and restarted after you finish active tasks. Pass the same CODEAFAR_DATA_DIR when customized. After migration, use codeafar update. For a new install, use the installer above.

指定 App 真正能访问的 Host 地址。Use the Host address the app can actually reach.

--endpoint 中的 IP 或域名属于运行 CodeAfar Host CLI 的电脑，或者转发到它的 FRP 入口。它会写入配对 JSON，省去在 App 中再次输入地址。

The IP or domain in --endpoint belongs to the computer running CodeAfar Host CLI, or to an FRP gateway forwarding to it. It is embedded in pairing JSON so the app does not need a second address entry.

# frpc.toml (on the Host)
[[proxies]]
name = "codeafar"
type = "tcp"
localIP = "127.0.0.1"
localPort = 7443
remotePort = 17443

从 Host、目录到第一次指令。From Host and folder to the first instruction.

1. 1
   点击 New task 并选择 HostSelect New task and choose a Host

   多 Host 环境下先确认在线状态与主机名。

   In a multi-Host setup, confirm the hostname and online state first.

2. 2
   选择 Codex 或 Claude CodeChoose Codex or Claude Code

   Provider 在创建 Session 时固定；模型与 Effort 选项由 Host 实时返回。

   The provider is fixed when the session is created; models and effort options come from the Host.

3. 3
   选择或创建工作区Select or create a workspace

   可见范围由 Host 的 Restricted roots 或 Full access 决定。

   Visible folders are controlled by the Host's restricted roots or full access.

4. 4
   发送指令并跨设备继续Send an instruction and continue across clients

   消息、审批、工具活动与历史属于同一个 Host Session。Plan、Goal、Effort 等选项取决于所选 Provider 与版本；未支持的能力不会伪装为已完成。

   Messages, approvals, tool activity, and history belong to the same Host session. Plan, Goal, effort, and other options depend on the provider and version; unavailable capabilities are not represented as completed.

同一项工作，在终端与 App 继续。Continue the same work in Terminal and the app.

在已经配置并运行 CodeAfar Host 的电脑上，以同一系统用户运行以下命令。目录必须位于 Host 的授权范围。Codex 使用原生终端界面连接共享 app-server；Claude 使用 CodeAfar 的共享终端入口，与 App 共用 Host 中的同一个 Claude 运行实例。

Run these as the same OS user on a configured, running CodeAfar Host. Choose an authorized folder. Codex opens its native TUI on the shared app-server; Claude uses the CodeAfar terminal front end attached to the same Host-owned Claude runtime as the apps.

继续已有会话时追加 --session SESSION_ID（用实际会话 ID 替换）。App 打开同一 Host 的同一会话后可查看增量输出；运行中的补充指令与停止操作绑定当前轮次，不会误发到下一轮。关闭终端连接不会主动停止 Host 中的任务。

Add --session SESSION_ID, replacing the placeholder with the existing session ID. Open the same session on the same Host in the app to see incremental progress. Supplementary instructions and Stop target the observed turn, never a later one. Detaching Terminal does not deliberately stop the Host task.

地址负责路由，凭据负责信任。Endpoints route. Credentials establish trust.

配对 JSON 中的端点可以按网络环境变化，但 App 仍会校验 Host 证书指纹。会话数据通过已认证的加密通道传输。Provider 登录凭据不通过 App 配置；代码执行在 Host 上，您查看的对话、代码片段与附件会传到已配对 App。

The endpoint may change with the network, while the app still verifies the Host certificate fingerprint. Session data travels over an authenticated encrypted channel. Provider credentials are not configured through the app. Code executes on the Host; conversations, code excerpts, and attachments you view are transmitted to paired apps.

为人设计默认输出，为自动化保留稳定 JSON。Readable by default, stable JSON for automation.

CodeAfar CLI 默认显示简洁状态、必要字段与下一步提示。命令组可直接运行：codeafar host 等同于查看状态，roots、devices、providers 直接列出当前内容。追加 --json 才会输出 App 和脚本使用的原始结构。

CodeAfar CLI defaults to concise status, essential fields, and next actions. Command groups work directly: codeafar host shows status, while roots, devices, and providers list their current state. Add --json only for app or script data.