电脑

如果你已经在电脑上使用 Claude Code、Codex 等 AI 编程工具，HiFox 不会替代它们。HiFox 连接这台电脑，把可用的 AI 编程工具登记为运行时（Runtime），再让配置好的 Agent 在任务中调用它们。

理解这篇文档，需要先区分四个概念：

  • Agent：HiFox 中“如何工作”的配置，包括职责、指令、Skill、代码库和所选 Runtime。详见 Agent。
  • Runtime：实际执行工作的 AI 编程工具或执行入口，例如 Claude Code、Codex。
  • 电脑：Runtime 真正运行的机器，提供操作系统、代码、凭据、工作目录、网络和计算资源。
  • 本地服务：运行在电脑上的后台程序，负责连接 HiFox、接收任务、准备环境、启动 Runtime，并回传进展和结果。

一次任务的执行链路大致如下：

任务
  → HiFox 组合任务上下文和 Agent 配置
  → 派发到电脑上的本地服务
  → 本地服务准备代码和工作目录
  → 启动 Agent 选择的 Runtime（例如 Claude Code、Codex）
  → 进展和结果写回 HiFox 任务

本页重点介绍电脑、Runtime 及其运行条件。完整的任务派发和状态变化见 Agent 如何执行任务。

Runtime：电脑上的 AI 编程工具

一台电脑可以提供一个或多个 Runtime。例如，同一台电脑可能同时检测到 Claude Code、Codex 或其他支持的 AI 编程工具。创建或配置 Agent 时，可以选择它使用哪个 Runtime。

Runtime 决定实际启动的工具及其默认模型；Agent 负责保存工作方式和调用配置。

电脑详情中的 Runtime 列表

电脑在线并不等于 Agent 一定能执行任务：在线只说明本地服务的心跳正常；只有 Agent 所选的 Runtime 可用，任务才具备启动条件。

Runtime 能力状态

电脑详情会分别显示每个 Runtime 的能力状态：

状态含义和下一步
可用Runtime 已连接并具备执行条件，可以用于 Agent 任务。
需配置Runtime 已被检测到，但还缺少必要配置；按详情页提示补充配置后再测试。
未安装本地服务找不到对应工具，需要先安装，或为 Agent 选择其他 Runtime。
不支持当前 Runtime 或电脑环境不满足支持条件，应改用受支持的 Runtime 或电脑。

如果刚安装了 Claude Code、Codex 等工具，通常需要让本地服务重新检测。工具还必须对本地服务的运行用户可见，例如能从该用户的 PATH 中找到。

安装 Runtime

当 Runtime 状态显示「未安装」时，先在这台电脑上安装对应工具，再让本地服务重新检测。电脑在线只表示本地服务仍在发送心跳，并不表示所选 Runtime 已具备执行条件。

电脑详情会根据当前 Runtime 选择器和支持矩阵，为已支持的 Runtime 提供对应的官方安装指南。服务商页面和支持范围可能变化，请优先使用线上 Runtime 详情中的链接，不要根据本文固定列表推断平台限制或安装命令。

安装后回到电脑详情，使用页面提供的重新检测或测试连接入口，确认本地服务能看到 Runtime。具体按钮名称、可用平台和支持范围以线上产品为准。

配置已检测的 Runtime

电脑所有者可以在已检测 Runtime 的详情中配置执行程序、默认附加参数和默认环境变量；执行程序可以替换检测到的默认位置。这些值会为使用该 Runtime 的 Agent 提供默认启动配置，不会创建新的自定义 ACP Runtime。Agent 中为同一个参数或环境变量设置的值优先于 Runtime 默认值。

保存执行程序前，HiFox 会检查它能否执行，以及是否与该 Runtime 的供应商和版本兼容。检查失败时，现有配置会保留，不会被失败的输入覆盖。修改后请使用测试连接或重新检测，确认本地服务仍能启动 Runtime；如果卸载了对应工具，也需要重新检测，才能更新它的状态。

电脑级别的「无 Runtime」表示这台电脑当前没有报告可供选择的 Runtime，是汇总状态，不等同于某个 Runtime 的「未安装」「需配置」或「可用」。无论电脑是否在线，都要以所选 Runtime 的检查或测试结果为准。

只填写产品要求的配置。不要在执行程序、附加参数或其他不适用字段中保存密码、Token、API Key、私钥或其他敏感信息。

选择并连接电脑

HiFox 可以连接本地电脑、远程服务器或 Docker 容器。选择哪一种，取决于任务需要使用的环境和资源。

类型适合场景主要特点
本地电脑个人开发、复用已有本机环境可以使用本机 SSH key、依赖缓存、内部工具和调试脚本。
远程电脑长时间运行、团队共享或较重的任务更适合持续在线，也可以靠近团队的内部网络、服务和共享资源。

个人电脑通常保持个人可见；需要多人共用时，更建议准备专门的远程电脑，而不是直接共享个人开发环境和凭据。

连接新电脑

一般流程是：

  1. 在 HiFox 中选择连接新电脑；
  2. 选择目标平台，例如 macOS、Windows、Linux 或 Docker；
  3. 安装 HiFox 桌面端、CLI 或本地服务；
  4. 使用安装令牌完成注册；
  5. 确认本地服务正在运行；
  6. 回到 HiFox，确认电脑在线，并且至少有一个 Runtime 可用。

在远程电脑或命令行环境中，可以使用连接向导提供的注册命令：

hifox computer register --install-token hit_...

安装令牌通常有有效期，并且只能使用一次。不要把安装令牌放进镜像、任务描述、评论或长期脚本；如果令牌过期或已经使用，请重新生成。

本地服务会主动连接 HiFox，因此常规连接通常不需要对外开放入站端口。

确认电脑可以执行任务

连接完成后，需要分别确认电脑连接状态和 Runtime 能力状态。

电脑连接状态

常见状态包括：

  • 在线：最近收到本地服务心跳，可以接收任务；
  • 最近失联：短时间失去连接，可能是网络或本地服务暂时中断；
  • 离线：一段时间没有心跳，新任务会排队或无法开始；
  • 即将清理：长时间离线，相关电脑记录可能会被系统自动清理。

电脑在线后，再检查 Agent 所选 Runtime 是否为可用。如果 Runtime 显示需配置、未安装或不支持，任务仍然无法真正启动。

使用 CLI 检查

可以在目标电脑上运行：

# 检查本地服务
hifox computer status
hifox computer logs -n 100

# 检查组织中的电脑和 Runtime
hifox computer list
hifox computer show <computer-id>
hifox computer ping <computer-id> <runtime-id> --wait

status 和 logs 用于检查当前电脑上的本地服务；list 和 show 用于确认注册信息与 Runtime；ping 用于验证指定 Runtime 能否通过本地服务完成一次往返。完整命令见 HiFox CLI。

用低风险任务验证

页面显示在线之后，建议先创建一个只读任务：

请读取项目 README，确认项目使用的主要语言、包管理器和最接近的测试命令。不要修改文件，并注明支持每项结论的文件。

这个任务可以同时验证：

  • Agent 是否选择了正确的电脑和 Runtime；
  • Claude Code、Codex 等工具能否真正启动；
  • 电脑能否访问仓库和工作目录；
  • Agent 能否读取文件并把结果写回任务。

确认只读任务成功后，再让 Agent 修改代码或运行更复杂的命令。

Agent 如何使用电脑

一台电脑可以服务多个 Agent。Agent 通过所选 Runtime 使用电脑上的代码、命令、凭据和计算资源。

任务可能因为以下原因排队或无法开始：

  • 电脑离线；
  • 所选 Runtime 不可用；
  • 电脑或 Agent 的并发已满；
  • 指定已有目录正被其他任务占用；
  • 代码库、凭据或必要命令不可用。

并发和工作目录

如果 Agent 使用独立临时目录，不同任务通常可以在各自的 Git worktree 中并行运行，避免直接修改同一个工作区。

如果 Agent 使用指定已有目录，同一个目录通常只能同时运行一个任务。没有空闲目录时，任务会等待本地目录可用。

默认并发规则：

  • 指定已有目录：默认并发等于已配置的目录数；
  • 独立临时目录：默认并发是电脑并发的 50%。

并发越高，对 CPU、内存、磁盘和网络的压力越大。工作目录模式、任务状态和完整执行过程见 Agent 如何执行任务。

代码库、凭据和运行环境

HiFox 保存代码库和 Agent 配置，但真正执行 clone、git、gh、构建和测试命令的是 Agent 所在的电脑。

请确保本地服务的运行用户能够：

  • 访问目标 Git 仓库；
  • 使用所需的 SSH key、HTTPS token 或其他代码托管凭据；
  • 读取和写入任务工作目录；
  • 使用项目需要的包管理器、构建工具、测试命令和内部服务。

如果电脑无法 clone 仓库，Agent 也无法完成代码任务。仓库来源、指定已有目录和凭据规则见 连接代码库。不要把密码、Token、API Key 或私钥写进任务描述和评论。

管理电脑

可见性和允许的组织

电脑可以设置为：

  • 个人：只有所有者可以使用；
  • 组织：组织中的成员可以使用；
  • 空间：所选空间中的成员可以使用。

可见性决定组织内哪些人可以看到和选择电脑。对于本地个人电脑，所有者还可以决定哪些组织能够使用它：

  • 所有组织：所有者当前加入以及之后加入的组织都可以使用；
  • 选定的组织：只允许所有者明确选择的组织使用。

可见性和允许的组织是两层不同的限制。只有电脑所有者可以修改个人电脑允许的组织；组织 Owner 或 Admin 不会因为组织角色而自动获得管理其他人个人电脑的权限。

防止休眠

防止休眠只出现在桌面端的本机电脑，不会出现在共享或远程电脑上。

开启后会阻止系统睡眠，但屏幕仍可按系统设置熄灭。这不是保持亮屏；它的作用是避免本机任务和 Agent 连接因系统睡眠中断。

可选时长包括 5 分钟、30 分钟、1 小时、2 小时、5 小时、8 小时和始终。时长到期后会自动关闭；修改时长会重新计时。

合盖时不休眠是独立选项，仅在 macOS 且系统能力可用时出现。没有连接电源时，界面会提示连接电源后再试；系统不支持时，这个选项不会出现。

磁盘占用和自动清理

Agent 运行会留下工作目录、缓存和运行产物。可以在桌面端本地服务或电脑设置中配置：

  • 清理频率；
  • 终态运行保留天数；
  • 最低可用空间；
  • 缓存到期后额外保留天数。

自动清理不会删除：

  • 正在运行或排队的任务；
  • pinned 的运行；
  • 仍需排查的失败运行；
  • ~/.claude/worktrees 等嵌套 Agent 缓存。

保存策略后，需要重启本地服务或重新注册电脑。不要手动删除不了解的本地服务目录。

需要立即检查或清理时，可以使用：

hifox daemon disk-usage
hifox daemon cleanup
hifox daemon cleanup --confirm

不加 --confirm 只会预览，不会真正删除。

高级 Runtime 配置

自定义 ACP Runtime

如果电脑上的执行能力没有被自动检测到，可以添加自定义 ACP Runtime：

  1. 在电脑详情中选择添加自定义 Runtime；
  2. 配置 Runtime 图标、名称和启动命令；
  3. 保存后选择测试连接，确认本地服务可以启动并连接该 Runtime；
  4. 后续按需编辑，或删除不再使用的自定义 Runtime。

只填写产品界面要求的配置，不要把密码、令牌或其他敏感信息写进不适用的字段或启动命令。

ACP adapter 的隔离环境

当 ACP adapter 缺少兼容的 Node.js 环境时，HiFox 会优先复用电脑上已有的兼容环境；必要时，只为该 adapter 准备由产品管理的隔离执行环境。

这个过程不会修改系统全局 Node.js、npm、shell 配置、项目目录或用户的版本管理器配置。如果准备失败，HiFox 会保留原有环境并提供手动修复指引，不会用失败结果覆盖现有配置。

macOS 上的 Codex 兜底

在 macOS 上，如果没有单独安装 Codex，但安装了 ChatGPT 桌面应用，本地服务可以把应用内置的 Codex CLI 登记为 Runtime。

仍建议优先使用你自行安装并放入 PATH 的 Codex；ChatGPT 应用内置版本只是兜底。这不适用于 Windows 或 Linux。

诊断电脑问题

如果 Agent 没有开始、一直排队或运行失败，建议按以下顺序排查：

  1. 电脑连接：电脑是否开机、网络是否可用、本地服务是否仍在运行；
  2. Runtime：Agent 所选 Runtime 是否可用，Claude Code、Codex 等工具是否能被运行用户找到；
  3. 网络：电脑是否能连接 HiFox 和任务依赖的内部服务；
  4. 代码库：电脑是否能 clone 目标仓库，Git 凭据是否有效；
  5. 工作目录：目录是否存在、可写，指定目录是否正被占用；
  6. 并发：电脑或 Agent 的并发是否已满；
  7. CLI 和认证：CLI 是否过旧、本地服务是否需要重新登录或注册。

对于远程电脑，在目标电脑上运行 hifox computer status 和 hifox computer logs -n 100，通常比只看网页状态更容易定位原因。

解绑 Agent 和删除电脑

电脑所有者可以在电脑详情的 Agents 区域，对单个 Agent 使用解绑运行时，或选择解绑全部，从而收回电脑而不删除 Agent。

解绑后：

  • Agent 不会被归档或删除，但需要重新选择电脑或 Runtime 才能继续运行；
  • 正在进行的运行会被取消，相关任务需要重新安排；
  • 电脑所有者不会因此获得编辑他人 Agent 的完整权限。

删除电脑会移除它在 HiFox 中的记录和关联 Runtime。如果仍有活跃 Agent 绑定，删除可能会被阻止，需要先解绑或重新分配。删除前也应确认没有正在运行的重要任务。

如果电脑上的本地服务仍在运行，它后续重新连接时可能再次注册这台电脑。

常见问题

检测不到 Claude Code、Codex 或其他工具怎么办？

先确认工具已经安装，并且在本地服务运行用户的 PATH 中可用。安装后让本地服务重新检测，并在电脑详情中检查 Runtime 能力状态。

远程电脑需要开放端口吗？

通常不需要。本地服务主动连接 HiFox，一般不需要开放入站端口。

本地电脑适合共享给团队吗？

个人电脑适合个人 Agent 和本地开发工作。团队共享任务更适合使用专门的远程电脑，避免共享个人凭据、工作目录和不稳定的本机在线状态。