机器 - Hifox Docs

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

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

机器和守护进程

机器通过守护进程（Daemon）连接到 HiFox。

守护进程运行在机器上，负责：

向 HiFox 注册这台机器；

定期发送心跳，报告机器在线状态；

检测可用的运行时和 AI 编程工具；

接收 HiFox 派发的 Agent 任务；

准备工作目录和代码库；

启动 Agent 所需的工具；

将运行进展、日志和结果回传给 HiFox。

守护进程通常只需要主动连接 HiFox，不需要你对外开放入站端口。

本地机器和远程机器

HiFox 中常见的机器类型包括：

本地机器

本地机器是你的个人电脑。使用桌面端时，HiFox 可以在本地检测工具、管理守护进程，并把这台电脑注册为可用机器。

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

远程机器

远程机器通常是服务器、云主机或团队共享机器。你可以通过连接向导在远程机器上安装 CLI、使用安装令牌或个人访问令牌完成登录，并启动守护进程。

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

连接新机器

连接机器的一般流程是：

在 HiFox 中选择连接新机器；

选择目标平台，例如 macOS、Windows、Linux 或 Docker；

安装 HiFox 桌面端或守护进程；

使用安装令牌或个人访问令牌完成登录；

启动守护进程；

回到 HiFox，确认机器已连接并显示在线。

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

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

机器状态

机器列表和详情页会显示机器状态。

常见状态包括：

在线：最近收到心跳，可以派发任务；

最近失联：短时间失去连接，可能是网络或守护进程短暂中断；

离线：一段时间没有心跳，新的任务会排队或失败；

即将清理：长时间离线，可能会被系统自动清理。

如果机器离线，先检查机器是否开机、网络是否可用、守护进程是否仍在运行，以及 CLI 是否需要更新或重新登录。

机器可见性

机器可以设置可见范围。

常见可见性包括：

个人：只有你可以使用；

组织：组织中的成员可以使用；

空间：所选空间可见。

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

运行时（Runtime）是什么？

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

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

如果机器在线，但没有检测到合适运行时，Agent 仍然无法真正执行任务。安装对应工具后，通常需要重启守护进程或让机器重新检测。

机器和 Agent 的关系

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

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

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

并发和工作目录

机器会影响 Agent 的并发能力。

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

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

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

机器访问代码库和密钥

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

因此你需要确保：

机器可以访问目标 Git 仓库；

SSH key、HTTPS token 或代码托管凭据可用；

需要的环境变量和密钥已经配置；

内部服务、包管理器和测试命令在这台机器上可用。

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

诊断机器问题

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

常见检查项包括：

机器是否在线；

守护进程是否仍在运行；

CLI 是否过旧或已退出登录；

网络是否可访问 HiFox；

运行时是否检测到需要的 AI 编程工具；

机器是否能 clone 目标仓库；

指定工作目录是否存在且可写；

当前并发是否已满。

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

删除机器

当机器不再使用时，可以从 HiFox 中删除。

删除机器会移除它在 HiFox 中的记录和关联运行时。如果这台机器仍在线，守护进程重新连接时可能会再次注册。

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

常见问题

机器在线但 Agent 仍不能运行怎么办？

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

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

先确认工具已经安装，并且在守护进程运行用户的 PATH 中可用。安装后可以重启守护进程，让机器重新检测。

远程机器需要开放端口吗？

通常不需要。守护进程主动连接 HiFox，一般不需要开放入站端口。

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

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

本地机器适合共享给团队吗？

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

机器

机器和守护进程#

本地机器和远程机器#

本地机器#

远程机器#

连接新机器#

机器状态#

机器可见性#

运行时（Runtime）是什么？#

机器和 Agent 的关系#

并发和工作目录#

机器访问代码库和密钥#

诊断机器问题#

删除机器#

常见问题#

机器在线但 Agent 仍不能运行怎么办？#

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

远程机器需要开放端口吗？#

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

本地机器适合共享给团队吗？#