#电脑

如果你已经在电脑上使用 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 在线或可执行。Runtime 的离线只表示它或本地服务暂时失去连接；它不等于工具未安装，也不等同于「尚未检测到」。电脑本身的「离线」是另一项独立状态。排查任务无法启动时，先查看所选 Runtime 的状态，再检查电脑连接。

#Runtime 能力状态

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

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

#安装 Runtime

当 Runtime 状态显示「尚未检测到」时，先在这台电脑上安装对应工具，再让本地服务重新检测。部分 Runtime 同时提供桌面应用和 CLI；HiFox 使用的是 CLI 版本，详情页会提示安装 CLI，而不是桌面版。没有独立 CLI 的 Runtime（例如 OpenClaw）不会出现这条提示。用户可见的 Runtime 名称以线上为准。

电脑在线只表示本地服务仍在发送心跳，并不表示所选 Runtime 已具备执行条件。若显示「检测失败」，请按详情页提示修正配置后重新检测或测试连接。如果检测或对话提示 Runtime 未登录或未授权，请按页面给出的命令，在目标电脑的终端完成该 Runtime 的登录或授权；这与 HiFox CLI 的 login --token 不是同一步。

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

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

#配置已检测的 Runtime

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

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

修改执行程序后，本地服务可能会短暂重启并复核配置。正在重启并复核是中间状态，不要把它当作最终失败，也不要重复提交互相冲突的恢复操作。等待状态变为成功、明确失败或超时；只有明确失败、超时或复核失败时，才按错误处理。成功后刷新电脑、Machine 和 Runtime 信息。

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

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

#选择并连接电脑

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

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

#连接新电脑

在 HiFox 桌面端连接新电脑时，CLI / 本地服务是推荐方式，连接窗口会默认展开该方式；在网页版中，桌面端仍是推荐入口。推荐顺序只影响入口展示，不改变各平台的连接步骤。

一般流程是：

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

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

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

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

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

#确认电脑可以执行任务

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

#电脑连接状态

常见状态包括：

• 启动中：本机本地服务正在启动或重启，不是离线。电脑和相关入口应显示为同一状态。尚未检测到、检测失败或未安装的 Runtime 仍显示为自身状态，不会改成启动中。网页没有本机时，左下角状态点保持灰色。绑定本机的 Agent 对话可能提示电脑启动中、请稍后。在电脑详情使用重启服务后进入启动中，成功后会提示重启成功。
• 升级中：桌面端正在自动升级本地服务时显示为升级中，不是离线，也不是失败。升级完成后电脑会自动回到在线，不必再点一次启动。如果在升级过程中或升级后选择停止，电脑保持停止。升级失败时按界面提示处理，然后可再次启动。
• 在线：最近收到本地服务心跳，可以接收任务；
• 最近失联：短时间失去连接，可能是网络或本地服务暂时中断；
• 离线：一段时间没有心跳，新任务会排队或无法开始；
• 即将清理：长时间离线，相关电脑记录可能会被系统自动清理。

电脑在线后，再检查 Agent 所选 Runtime 是否为可用。如果 Runtime 显示离线、尚未检测到或检测失败，任务仍然无法真正启动。

#桌面端启动被占用

在桌面端点本机「启动」时，如果本地服务已被占用：

• 本产品相关占用会在应用内自动恢复，不必转到终端；
• 其他程序占用时，会显示进程名和运行时长，需要确认后才能结束占用并启动；
• 识别不出占用者时，只说明原因，不会结束未知进程。

如果启动失败，可以再次点启动。旧版或异常本地服务残留时，按界面提示处理后再试。

#重启服务和停止服务

在电脑详情可以对本地服务使用 重启服务 和 停止服务：

• 重启服务：重启本地服务。该电脑上的 Runtime 和 Agent 会短暂离线。
• 停止服务：停止本地服务。停止后该电脑上的 Runtime 和 Agent 都将离线。

这与网页里点「启动」不是同一入口。停止后需要再启动，电脑才会重新上线。

#使用 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，通常比只看网页状态更容易定位原因。

连接、本机启动或 Runtime 检测卡住时，页面会提供 查看帮助文档。如果配置了交流群，还会出现 加 HiFox 群求助，可以扫码加入官方交流群。

#解绑 Agent 和删除电脑

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

解绑后：

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

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

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

#常见问题

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

先确认工具已经安装，并且在本地服务运行用户的 PATH 中可用。部分 Runtime 需要安装 CLI 版本，而不是桌面应用。安装后让本地服务重新检测，并在电脑详情中检查 Runtime 能力状态。如果提示未登录或未授权，按页面命令在目标电脑终端完成该 Runtime 的登录。

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

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

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

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