#电脑

电脑是 Agent 真正执行工作的地方。它可以是你的本地电脑、远程服务器或 Docker 容器。

Agent 本身是一组配置；电脑才是运行 Agent 工作的执行环境。当任务被安排给 Agent 后，HiFox 会把任务派发到 Agent 可用的电脑，由电脑上的本地服务接收任务、准备工作目录、启动 AI 编程工具，并把结果写回 HiFox。

#电脑和本地服务

电脑通过本地服务连接到 HiFox。

本地服务运行在电脑上，负责：

• 向 HiFox 注册这台电脑；
• 定期发送心跳，报告电脑在线状态；
• 检测可用的运行时和 AI 编程工具；
• 接收 HiFox 派发的 Agent 任务；
• 准备工作目录和代码库；
• 启动 Agent 所需的工具；
• 将运行进展、日志和结果回传给 HiFox。

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

#本地电脑和远程电脑

HiFox 中常见的电脑类型包括：

#本地电脑

本地电脑是你的个人设备。使用桌面端时，HiFox 可以在本地检测工具、管理本地服务，并把这台电脑注册为可用电脑。

本地电脑适合使用你已经配置好的开发环境，例如本机 SSH key、包管理器、代码缓存、内部工具和调试脚本。

#远程电脑

远程电脑通常是服务器、云主机或团队共享主机。你可以通过连接向导在远程电脑上安装 CLI、使用安装令牌完成连接，并启动本地服务。

远程电脑适合长时间运行、团队共享、处理较重任务，或需要靠近内部网络和服务的场景。

#连接新电脑

连接电脑的一般流程是：

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

安装令牌通常有有效期，并且只能使用一次。如果命令过期或已经使用，需要重新生成。

连接完成后，建议创建一个低风险任务，确认 Agent 能在这台电脑上启动、读取仓库并写回结果。

#电脑状态

电脑列表和详情页会显示电脑状态。

常见状态包括：

• 在线：最近收到心跳，可以派发任务；
• 最近失联：短时间失去连接，可能是网络或本地服务短暂中断；
• 离线：一段时间没有心跳，新的任务会排队或失败；
• 即将清理：长时间离线，可能会被系统自动清理。

如果电脑离线，先检查电脑是否开机、网络是否可用、本地服务是否仍在运行，以及 CLI 是否需要更新或重新连接。

#防止休眠

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

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

时长可选：

• 始终
• 5 分钟
• 30 分钟
• 1 小时
• 2 小时
• 5 小时
• 8 小时

时长到期后自动关闭。改时长会重新计时。「始终」不会到期。

合盖时不休眠是独立选项，仅 macOS 且能力可用时出现。没插电时，界面会提示「连接电源后再试」，不要把它写成已经生效。系统不支持时，这个选项也不会出现。

#电脑可见性

电脑可以设置可见范围。

常见可见性包括：

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

电脑可见性决定哪些人可以看到并选择这台电脑。对于本地电脑，通常建议保持个人可见；对于团队共享服务器，可以设置为组织或空间可见。

#允许的组织

本地个人电脑的所有者还可以选择哪些组织能够使用这台电脑：

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

这个设置只适用于本地个人电脑，且只有电脑所有者可以修改。组织 Owner 或 Admin 不会因为组织角色而自动获得管理其他人个人电脑的权限。

电脑可见性和允许的组织是两层不同的限制：前者决定组织内哪些人能看到或选择电脑，后者决定这台本地个人电脑在哪些组织中可用。

#运行时（Runtime）是什么？

一台电脑上可以有一个或多个运行时（Runtime）。运行时表示这台电脑上可用于 Agent 工作的具体工具或执行环境。

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

如果电脑在线，但没有检测到合适运行时，Agent 仍然无法真正执行任务。安装对应工具后，通常需要让本地服务重新检测。

#Runtime 能力状态

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

电脑显示在线，只代表本地服务的心跳正常，并不代表选定 Runtime 一定可以执行任务。若任务无法启动，先查看选定 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 会保留原有环境并提供手动修复指引，不会用失败的准备结果覆盖现有配置。

#电脑和 Agent 的关系

Agent 需要绑定电脑或运行时，才能执行任务。

一台电脑可以服务多个 Agent，一个 Agent 也可以根据配置使用指定电脑。电脑详情里通常可以看到当前有哪些 Agent 正在使用它，以及有多少任务正在运行或排队。

如果一个 Agent 的电脑离线，任务可能会排队等待；如果电脑并发已满，新的任务也会排队。

#解绑占用这台电脑的 Agent

电脑所有者可以在电脑详情的 Agents 区域，把占用这台电脑的某个 Agent 解绑，或一次性 解绑全部。单行操作是 解绑运行时。

这是所有者收回电脑的方式，和删除电脑不同：

• Agent 还在，不会被归档或删除；只是清空这台电脑作为它的执行目标，需要重新选电脑才能再跑；
• 进行中的运行会被取消；委派给该 Agent 的任务需要重新安排；
• 不因此获得他人 Agent 的完整编辑权。

确认弹窗文案以线上为准。删除电脑仍可能被活跃绑定挡住；解绑之后再删。

#并发和工作目录

电脑会影响 Agent 的并发能力。

如果 Agent 使用独立临时目录，任务通常可以在不同 worktree 中并行运行。每个任务有自己的代码工作区，不容易互相影响。

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

并发默认值：

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

两种都可以改成手动输入。如果手动填得比目录数大，界面会提示：

注意：当前设置的并发数大于指定的目录数量，如果 AI 存在写入操作会导致不同任务之间相互影响。

你可以在 Agent 或电脑相关设置中调整最大并发运行任务数，但不要盲目调高。并发越高，对 CPU、内存、磁盘和网络的压力越大。

#检查磁盘占用和自动清理

Agent 执行任务会留下工作目录、缓存和运行产物。桌面端本地服务和电脑设置里可以配置自动清理策略。

可配置项包括：

• 清理频率（小时）
• 终态运行保留天数
• 最低可用空间（GiB，0 表示禁用）
• 缓存到期后额外保留天数

默认比较积极：已完成或已取消等终态运行大约保留 7 天即可回收。也可以设置最低可用空间（保守默认 10 GiB；填 0 关闭）。空间不足时，只会在同一批安全候选里按体积优先回收。

不会自动回收：

• 进行中或排队的运行；
• pinned 的运行；
• 仍需排查的报错运行；
• ~/.claude/worktrees 这类嵌套 Agent 缓存。

保存后需要重启本地服务或重新注册电脑，策略才会生效。不要手删不理解的本地服务目录。

需要立刻查看或手动清理时，仍用 CLI：

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

不加 --confirm 只预览，不会真正删除。界面策略和 CLI 手动清理是互补的，不是互相替代。

#电脑访问代码库和密钥

Agent 访问 代码库 时，实际使用的是电脑上的 Git 凭证。

因此你需要确保：

• 电脑可以访问目标 Git 仓库；
• SSH key、HTTPS token 或代码托管凭据可用；
• 需要的环境变量和密钥已经配置；
• 内部服务、包管理器和测试命令在这台电脑上可用。

HiFox 可以管理代码库和密钥配置，但电脑本身仍然需要具备执行任务所需的访问能力。

#诊断电脑问题

如果 Agent 没有开始、一直排队或运行失败，可以从电脑开始排查。

常见检查项包括：

• 电脑是否在线；
• 本地服务是否仍在运行；
• CLI 是否过旧或已退出登录；
• 网络是否可访问 HiFox；
• 运行时是否检测到需要的 AI 编程工具；
• 电脑是否能 clone 目标仓库；
• 指定工作目录是否存在且可写；
• 当前并发是否已满。

电脑页面通常会提供诊断命令。对于远程电脑，在目标电脑上运行诊断命令会比只看网页状态更准确。

#删除电脑

当电脑不再使用时，可以从 HiFox 中删除。

删除电脑会移除它在 HiFox 中的记录和关联运行时。如果这台电脑仍在线，本地服务重新连接时可能会再次注册。

如果电脑仍绑定活跃 Agent，删除可能会被阻止。删除前建议先归档或重新分配相关 Agent，并确认没有正在运行的重要任务。

#常见问题

#电脑在线但 Agent 仍不能运行怎么办？

检查 Agent 是否选择了正确电脑或运行时，电脑上是否安装了需要的 AI 编程工具，以及任务所需的代码库和凭证是否可用。

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

先确认工具已经安装，并且在本地服务运行用户的 PATH 中可用。安装后可以让本地服务重新检测。

在 macOS 上，如果没有单独安装 Codex，只要安装了 ChatGPT 桌面应用，本地服务也可以把其中的 Codex CLI 登记为 Runtime。仍建议优先用你自己安装并放进 PATH 的版本；App 内置只是兜底。这不适用于 Windows / Linux。

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

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

#为什么任务一直等待本地目录？

通常是因为 Agent 使用指定已有目录，而所有可用目录都在被其他任务占用。等待当前任务结束，或配置更多目录。

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

通常不建议把个人电脑作为团队共享电脑。个人电脑适合个人 Agent 和本地开发工作；团队共享任务更适合使用远程电脑。