你要连接哪台电脑？Which computer are you connecting to?
连接地址永远指向运行 Codex CLI / Claude Code 与 CodeAfar Host 的电脑，不是运行 CodeAfar App 的手机或电脑。
The endpoint always identifies the computer running Codex CLI / Claude Code and CodeAfar Host—never the phone or computer running the CodeAfar app.
macOS 直装版 · 本机编程Direct macOS download · local coding
直接使用本机 Provider，无需另装 CodeAfar CLI，也无需配对。
Use local providers. No separate CodeAfar CLI or pairing.
TestFlight / 手机 / 远程电脑TestFlight / phone / remote desktop
安装 Host CLI，再选择局域网、组网或 FRP 地址。
Install Host CLI, then use a LAN, mesh, or FRP endpoint.
版本区别：官网直装版名为 CodeAfar Desktop，可连接本机及远程 Host；TestFlight 版名为 CodeAfar，仅连接远程 Host，不显示 Local。两版可以在同一台 Mac 共存。手机端始终没有本机 Host。下载开放状态以下载页为准。
Version differences: the direct-download CodeAfar Desktop supports local and remote Hosts. TestFlight CodeAfar is remote-only and has no Local entry. Both can coexist on a Mac. Phones never have a local Host. Check the downloads section for availability.
安装 TestFlight 版：先接受开发者发来的测试邀请，再在对应设备的 TestFlight 中安装或更新 CodeAfar。Mac 请选择兼容“这台 Mac”的原生 macOS 构建，不是“为 iPhone 设计”的应用。当前内部测试版本：macOS 0.1.0（7），iOS 0.1.0（7）。没有邀请时，请等待测试资格开放；官网不提供公开 TestFlight 邀请链接。
Install with TestFlight: accept the developer's testing invitation, then install or update CodeAfar in TestFlight on your device. On Mac, choose the native macOS build compatible with “this Mac,” not an app designed for iPhone. Current internal builds: macOS 0.1.0 (7), iOS 0.1.0 (7). An invitation is required; there is no public TestFlight invitation link.
同机使用，打开 App 即可。Same machine: just open the app.
此流程仅适用于官网 macOS 直装版 CodeAfar Desktop，不适用于 TestFlight。App 使用随包附带的本机连接组件，直接复用当前系统用户的 Codex CLI、Codex Desktop 所带 CLI 或 Claude Code 的配置与历史；无需另装 CodeAfar CLI。
This path is for the direct-download macOS CodeAfar Desktop, 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确认 Codex 或 Claude 可在终端运行Run Codex or Claude successfully in Terminal
- 2安装并打开 CodeAfar DesktopInstall and open CodeAfar Desktop
从官网下载 ZIP，解压后将
CodeAfar Desktop.app拖入“应用程序”，再打开。更新时先退出旧版，再替换应用包；无需删除用户配置或会话。安装包已使用 Developer ID 签名并通过 Apple 公证。侧边栏会出现带LOCAL标记的本机 Host。Download the ZIP from the official site, extract it, drag
CodeAfar Desktop.appinto Applications, then open it. To update, quit the old app before replacing its bundle; keep your configuration and sessions. The download is Developer ID signed and notarized by Apple. A Host markedLOCALappears in the sidebar. - 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”。iPhone、iPad 和 Android 必须连接另一台运行 CodeAfar Host CLI 的电脑。
Mobile has no “local Host.” iPhone, iPad, and Android must connect to another computer running CodeAfar Host CLI.
只在远程 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.
$ curl -fsSL https://codeafar.seekice.com/install.sh | sh默认写入 ~/.local/bin，不需要 sudo。
Installs to ~/.local/bin by default without sudo.
> irm https://codeafar.seekice.com/install.ps1 | iex安装后重新打开 PowerShell，使用户 PATH 生效。
Open a new PowerShell window afterward to refresh the user PATH.
运行引导式配置Run guided setup
setup 会依次设置 Host 名称、监听地址、授权目录并安装用户级后台服务。默认采用 Restricted 权限，任何远程监听或 Full access 都会明确显示并确认。
setup configures the Host name, listen address, authorized roots, and per-user background service. Restricted access is the default; remote listening and Full access remain explicit.
$ codeafar setup检查或安装更新Check for or install updates
Host 最多每天检查一次签名清单，只提示、不自动安装。--check 仅检查；update 才会下载。下载会显示百分比、速率和预计时间，支持失败重试与断点续传。CLI 会验证 Ed25519 签名、归档大小和 SHA-256，再原子替换程序；若服务重启健康检查失败则自动回滚。配置、授权目录、设备和会话数据库都会保留。
The Host checks the signed manifest at most daily and only notifies—it never auto-installs. --check checks; update downloads with percent, rate, ETA, retry, and resume. The CLI verifies the Ed25519 signature, size, and SHA-256 before atomic replacement, and rolls back if the restarted service fails its health check. Configuration, roots, devices, and sessions are preserved.
$ codeafar update --check$ codeafar update确认 Provider 已安装并登录Confirm the provider is installed and signed in
先在 Host 终端成功运行一次 codex 或 claude。Claude Code 是可选项。
Run codex or claude successfully once in the Host terminal. Claude Code is optional.
$ codeafar doctordoctor 现在输出易读的检查清单和可直接执行的修复提示。脚本需要原始字段时追加 --json。缺少 Claude 不会影响 Codex。
doctor now prints a readable checklist with executable repair hints. Add --json when a script needs the raw fields. Missing Claude does not affect Codex.
明确开放监听与文件范围。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.
监听所有可用网卡Listen on all available interfaces
$ codeafar host configure --listen 0.0.0.0:7443 --enable-remote0.0.0.0 是服务端监听地址，意思是接受到达这台 Host 的所有 IPv4 网卡流量。它不能作为 App 的连接地址。
0.0.0.0 is a server listen address: accept traffic arriving on any IPv4 interface. It is not a destination the app can connect to.
授权可用文件夹Authorize workspace folders
$ codeafar access restricted$ codeafar roots add /absolute/path/to/projectsRestricted 模式只允许 App 在已加入根目录及其子目录中选择或新建工作区。可重复添加多个绝对路径。
Restricted mode lets the app choose or create workspaces only inside added roots. Repeat with additional absolute paths as needed.
$ codeafar access fullFull access 会开放该 Host 系统用户本来可访问的所有目录，并在交互式终端要求确认。自动化环境必须显式追加 --yes。
Full access exposes every directory available to the Host OS user and asks for confirmation in a terminal. Non-interactive automation must explicitly add --yes.
启动并检查 HostStart and inspect the Host
$ codeafar host install$ codeafar host status状态页会直接显示 Running、Starts at boot 和 PID。Linux 如果尚未开启 linger，会同时显示原因和可复制的一次性 sudo loginctl enable-linger <uid> 命令；执行后 Host 会随系统启动并在 SSH 退出后继续运行。
Status directly shows Running, Starts at boot, and PID. If Linux linger is disabled, it prints the reason and a copyable one-time sudo loginctl enable-linger <uid> command; afterward the Host starts at boot and survives SSH logout.
$ codeafar host serve终端会显示实际监听地址；保持窗口打开。
The terminal shows the effective listen address. Keep the window open.
指定 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.
同一局域网Same local network
使用 Host 在路由器局域网中的地址。示例中 192.168.1.20 是 Host，不是手机。
Use the Host address on the router's LAN. In this example, 192.168.1.20 is the Host, not the phone.
$ codeafar pair create --json --endpoint wss://192.168.1.20:7443/capTailscale / ZeroTier
使用 Host 的组网 IP 或组网 DNS 名称。两端设备需已加入同一 Tailnet 或 ZeroTier Network。
Use the Host's mesh IP or mesh DNS name. Both devices must join the same Tailnet or ZeroTier network.
$ codeafar pair create --json --endpoint wss://100.101.102.103:7443/capdev-mac.tailnet.ts.net。MagicDNS names such as dev-mac.tailnet.ts.net also work.经 FRP 访问Connect through FRP
使用 TCP 代理把公网端口原样转发到 Host 的 7443。必须保留 CodeAfar 自己的 TLS，不要使用会终止或替换证书的 HTTP/HTTPS 代理。
Use a TCP proxy that forwards a public port unchanged to Host port 7443. Preserve CodeAfar TLS; do not use an HTTP/HTTPS proxy that terminates or replaces its certificate.
# frpc.toml (on the Host)
[[proxies]]
name = "codeafar"
type = "tcp"
localIP = "127.0.0.1"
localPort = 7443
remotePort = 17443$ codeafar pair create --json --endpoint wss://frp.example.com:17443/cap端点必须以 wss:// 开头并以 /cap 结束。不要填写 0.0.0.0；它只用于 Host 监听。不要把一次性配对 JSON 发送给不受信任的人。
The endpoint must start with wss:// and end in /cap. Never enter 0.0.0.0; it is listen-only. Do not share one-time pairing JSON with anyone you do not trust.
在 App 中粘贴 JSONPaste JSON in the app
- 01
在 Host 终端生成配对信息Create pairing data on the Host
选择上面与你网络相符的命令。一次性密钥默认 5 分钟过期且只能成功使用一次。
Use the command matching your network. The one-time secret expires after five minutes and succeeds only once.
- 02
打开 CodeAfar 的 Pair hostOpen Pair host in CodeAfar
首次启动直接进入配对；之后可从 Settings → Paired computers 添加 Host。
First launch opens pairing directly; later use Settings → Paired computers.
- 03
粘贴完整 JSON 并安全配对Paste the full JSON and pair securely
App 会读取端点、验证证书指纹并创建设备签名身份。
The app reads the endpoint, pins the certificate fingerprint, and creates a device signing identity.
需要临时改地址时，分开填写Enter routing separately when needed
$ codeafar pair create --json不带 --endpoint 时，JSON 只包含端口、一次性密钥和指纹。随后在 App 的 “Reachable Host address” 填入当前可达地址，例如从局域网切换到组网 IP，而无需让 CLI 猜测网络环境。
Without --endpoint, JSON carries only the port, one-time secret, and fingerprint. Enter the current route in “Reachable Host address,” for example when switching from LAN to a mesh IP.
从 Host、目录到第一次指令。From Host and folder to the first instruction.
- 1点击 New task 并选择 HostSelect New task and choose a Host
多 Host 环境下先确认在线状态与主机名。
In a multi-Host setup, confirm the hostname and online state first.
- 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选择或创建工作区Select or create a workspace
可见范围由 Host 的 Restricted roots 或 Full access 决定。
Visible folders are controlled by the Host's restricted roots or full access.
- 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.
地址负责路由，凭据负责信任。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.
“Full access” 描述的是 Host 文件权限，并不绕过 Codex / Claude 自己的审批策略。使用公网 FRP 会扩大可扫描攻击面，应配合云防火墙来源限制，并及时撤销不再使用的配对设备。
“Full access” describes Host file scope and does not bypass provider approval policy. Public FRP increases the exposed attack surface; restrict source IPs and revoke devices you no longer use.
为人设计默认输出，为自动化保留稳定 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.
$ codeafar setup$ codeafar host$ codeafar host configure$ codeafar host install$ codeafar host start$ codeafar host stop$ codeafar access$ codeafar roots$ codeafar roots remove ROOT_ID$ codeafar devices$ codeafar devices revoke DEVICE_ID$ codeafar providers$ codeafar pair create$ codeafar pair create --json --endpoint wss://HOST:7443/cap$ codeafar context status$ codeafar update --check$ codeafar doctor$ codeafar logs --lines 200$ codeafar logs --follow$ codeafar version全局输出选项Global output options
$ codeafar host status --json$ codeafar doctor --quiet$ codeafar host status --color never--json 保持 stdout 为 JSON，失败时 stderr 返回带稳定 code、message 与 hint 的 JSON 错误；成功退出码为 0，参数或操作失败为非 0。--quiet 关闭成功提示，--verbose 开启诊断日志，--color auto|always|never 控制 ANSI 颜色并遵循 NO_COLOR。
--json keeps stdout as JSON and returns a JSON error with stable code, message, and hint on stderr. Success exits 0; argument or operation failures are non-zero. --quiet suppresses success output, --verbose enables diagnostics, and --color auto|always|never controls ANSI color while honoring NO_COLOR.
危险操作与无人值守脚本Destructive operations and scripts
Full access、移除授权根目录、撤销设备和卸载服务会在终端以默认 No 进行确认。只有已经审查过目标的无人值守脚本才应追加 --yes；--json 模式不会尝试读取交互输入。
Full access, root removal, device revocation, and service uninstall prompt with a default of No. Add --yes only in unattended scripts that have already validated the target; --json never tries to read an interactive response.
$ codeafar devices revoke DEVICE_ID --yes --json代理、更新检查与补全Proxy, update checks, and completion
更新下载遵循 HTTPS_PROXY、HTTP_PROXY 和 NO_PROXY。后台只做低频可用性检查，不含遥测；可用 codeafar host configure --no-update-check 或环境变量 CODEAFAR_DISABLE_UPDATE_CHECK=1 关闭。Shell 补全可生成到标准输出。
Update downloads honor HTTPS_PROXY, HTTP_PROXY, and NO_PROXY. The background task performs only a low-frequency availability check with no telemetry; disable it with codeafar host configure --no-update-check or CODEAFAR_DISABLE_UPDATE_CHECK=1. Shell completions are generated on stdout.
$ codeafar completion zsh > ~/.zfunc/_codeafar先检查可达性，再检查身份。Check reachability, then identity.
Codex CLI 能用，但 CodeAfar 返回 403Codex CLI works but CodeAfar receives 403＋
先查看错误原因。如果上游提示 This account only allows Codex official clients，说明该账户或网关拒绝第三方客户端，而不是配对失败。请让上游管理员允许 CodeAfar，或在 Host 上配置允许第三方 app-server 接入的账户。重新配对、反复发消息或重建会话都不能解除这项限制；CodeAfar 不会冒充官方客户端。其他 403 错误还需检查模型权限与账户状态。
If the upstream says This account only allows Codex official clients, its account or gateway policy rejects third-party clients. Ask the administrator to allow CodeAfar, or configure a permitted account on the Host. Re-pairing, resending, and recreating a session cannot remove this restriction. CodeAfar does not impersonate official clients. Other 403 errors may require checking model and account permissions.
配置了 Key，旧会话仍提示 Provider errorConfigured a key but an existing session still fails＋
不要删除会话。先以 Host 服务的同一用户、同一项目目录运行 claude 或 codex 并发送一条测试消息，再在 App 的该 Host → AI providers 中点击 Check again。终端临时 export 的变量不会自动进入已经启动的后台服务；请按 Provider 官方方式持久化配置，必要时在任务空闲后执行 codeafar host stop 和 codeafar host start。错误也可能是版本不兼容、代理不可达或额度不足，并不一定是 Key 错误。不要在 App、网站或问题报告里提交 Key。
Do not delete the session. Run the provider as the Host service user in the same workspace and send a test message, then choose Check again under that Host's AI providers. Variables exported in a terminal do not reach an already-running service. Persist configuration using your provider's official setup, and if needed stop/start the Host after active tasks finish. Version incompatibility, proxy access, and quota can also cause errors. Never submit keys to the app, website, or issue reports.
App 无法连接 HostThe app cannot reach the Host＋
在 Host 运行 codeafar host status 和 codeafar doctor。确认 App 填写的是 Host 的局域网/组网地址或 FRP 入口，而不是 0.0.0.0、127.0.0.1 或 App 自己的 IP。再检查 TCP 7443 或映射端口是否可达。
Run codeafar host status and codeafar doctor. Ensure the app uses the Host LAN/mesh address or FRP gateway—not 0.0.0.0, 127.0.0.1, or the app device IP. Then verify TCP 7443 or the mapped port is reachable.
FRP 能连端口但配对失败FRP port is open but pairing fails＋
确认代理类型为 TCP，并原样透传 CodeAfar TLS。HTTP/HTTPS 反向代理、CDN 或证书替换会导致指纹校验失败。重新生成包含公网 FRP 端点的配对 JSON。
Use a raw TCP proxy that preserves CodeAfar TLS. HTTP/HTTPS reverse proxies, CDNs, or certificate replacement break fingerprint verification. Create fresh pairing JSON with the public FRP endpoint.
配对码过期或已经用过The pairing code expired or was already used＋
回到 Host 重新运行 codeafar pair create --json --endpoint ...。每个码仅供一台客户端成功配对一次。
Run codeafar pair create --json --endpoint ... again on the Host. Each code pairs one client successfully once.
Codex 或 Claude 显示不可用Codex or Claude is unavailable＋
以运行 Host 的同一系统用户在终端执行 Provider CLI 并完成登录，再运行 codeafar doctor。没有安装 Claude 时 Codex 仍可独立使用。
Run and sign in to the provider CLI as the same OS user running the Host, then run codeafar doctor. Codex still works when Claude is not installed.
SSH 退出后 Host 离线The Host stops after SSH logout＋
运行 codeafar host status。Linux 用户服务需要启用 linger 才能脱离登录会话持续运行；按状态输出中 Try 下方的一次性命令执行，再确认 Starts at boot 显示 yes。
Run codeafar host status. A Linux user service needs linger to remain alive outside a login session; run the one-time command printed under Try, then confirm Starts at boot says yes.
codeafar update 看起来没有进度codeafar update shows no progress＋
先确认版本为 0.1.0-beta.10 或更新版本：codeafar version。新版会持续显示百分比、已下载大小、速率与预计时间，并自动重试。代理网络请设置 HTTPS_PROXY；进一步排查可运行 codeafar update --check --verbose。
Confirm 0.1.0-beta.10 or newer with codeafar version. Current builds continuously show percent, bytes, rate, and ETA with automatic retries. Set HTTPS_PROXY when required, then try codeafar update --check --verbose.
工作区为空或无法创建文件夹No workspace is available＋
在 Host 本机运行 codeafar access status，并用 codeafar roots add /绝对路径 添加授权根目录。App 不能远程扩大 Restricted 模式的根目录。
Run codeafar access status on the Host and add a root with codeafar roots add /absolute/path. The app cannot remotely expand restricted roots.
运行 codeafar doctor 与 codeafar logs --lines 200，保留脱敏输出和 App 错误信息。
Run codeafar doctor and codeafar logs --lines 200, then keep redacted output with the app error.