HiFox CLI

HiFox CLI 是在终端中使用 HiFox 的命令行工具。它既是人类在命令行里管理 HiFox 的入口，也是 Agent、脚本和自动化流程操作 HiFox 的入口。

通过 CLI，你可以创建任务、修改任务状态、添加评论、指派给成员 / Agent / 小队、查询组织资源，也可以在本机或远程机器上启动 daemon，让 Agent 在这台机器上执行任务。

如果你只是日常在网页或桌面端里创建任务、查看看板，不一定需要直接使用 CLI。通常在这些场景下会用到 CLI：

让 Agent 或脚本创建任务、更新任务状态、添加评论和读取任务上下文；

在终端中管理任务、Agent、项目、仓库、Skill 等资源；

在远程服务器上连接一台机器；

启动、停止或检查本机 daemon；

配置自托管或非默认 HiFox 服务地址；

排查机器离线、daemon 未启动或运行环境未检测到的问题。

安装前需要准备什么？

安装和使用 CLI 前，建议先确认：

你有 HiFox 账号；

机器可以访问 HiFox API；

如果要让 Agent 在这台机器上执行任务，机器上至少安装了一个支持的 AI 编程工具，例如 Claude Code、Codex、Gemini、OpenClaw、Hermes、Cursor Agent 或 GitHub Copilot CLI；

如果要访问代码库，机器上的 Git 凭证、SSH key、包管理器和内部网络访问已经准备好。

CLI 本身只负责连接和调度。真正读代码、改文件和运行命令，发生在 daemon 启动的 Agent 运行环境中。

安装 CLI

macOS / Linux

可以使用安装脚本安装：

默认会安装到 /usr/local/bin。如果这个目录不可写，脚本可能会使用 sudo。

也可以指定安装目录，例如：

安装脚本会自动识别系统和架构，下载对应包并校验 checksum。macOS 和 Linux 支持 amd64 / arm64；macOS Intel 会使用 universal 包。

安装完成后，可以检查版本：

Windows

Windows 可以使用 PowerShell 安装：

iwr https://file-assets.hifox.cn/download/install.ps1 -UseBasicParsing -OutFile install.ps1
powershell -File install.ps1 -Product hifox -BinaryName hifox -BaseUrl https://file-assets.hifox.cn/download

默认会安装到：

%USERPROFILE%\.hifox\bin\hifox.exe

安装脚本会尝试把安装目录加入用户 PATH。PATH 更新后，通常需要重新打开终端。

当前 Windows 安装脚本支持 Windows AMD64，不支持 Windows ARM64。

登录 CLI

CLI 登录使用个人访问令牌。当前 CLI 不使用浏览器登录流程。

推荐先在 HiFox 中创建一个个人访问令牌，然后运行：

CLI 会提示你粘贴令牌。也可以直接传入：

登录成功后，CLI 会验证令牌、保存到当前 profile，并尝试发现你所在的组织。如果当前 profile 还没有默认组织，CLI 会自动设置一个默认组织。

检查当前登录状态：

退出当前 profile 的登录：

注意：auth logout 只会移除本机保存的令牌，不会吊销服务端的个人访问令牌。如果要让令牌彻底失效，请到 设置 → 个人访问令牌 中删除对应令牌。

一步完成配置和启动

如果你是在自己的机器上使用个人访问令牌连接 HiFox，可以使用 setup 流程：

它会完成这些动作：

配置 HiFox Cloud 服务地址；

提示你输入个人访问令牌；

验证账号并保存登录信息；

发现并设置默认组织；

启动 daemon。

如果已有服务地址配置，CLI 可能会询问是否覆盖。

自托管环境可以使用：

也可以先手动配置地址，再登录：

使用安装令牌连接机器

如果你是在 HiFox 网页或桌面端里点击“连接机器”，通常会得到一条带安装令牌的命令。这个流程应使用 connect machine，而不是 login --install-token。

示例：

连接成功后，CLI 会：

为本机创建或复用本地机器身份；

用安装令牌向 HiFox 交换机器会话；

创建一个机器专用 profile；

保存机器连接信息；

尝试重启 daemon，让这台机器上线。

安装令牌通常有有效期，并且只能使用一次。如果提示令牌无效、过期或已使用，请回到 HiFox 重新生成连接命令。

安装令牌和个人访问令牌不同：

令牌	前缀	用途
个人访问令牌	`hfx_`	代表你的账号登录 CLI 或访问 API。
机器安装令牌	`hit_`	用于把一台机器连接到组织，通常由连接机器向导生成。

管理 daemon

常用 daemon 命令：

如果要在当前终端前台运行 daemon，可以使用：

查看结构化状态：

查看最近日志：

持续跟随日志：

daemon 已经运行时，再执行 hifox daemon start 不会重复启动。遇到机器离线、任务不运行、运行时检测不到等问题时，优先查看：

检查磁盘占用和清理

Agent 执行任务会创建工作目录、缓存和运行产物。你可以用 CLI 查看 daemon 管理目录的磁盘占用：

按组织查看：

清理过期或可清理的运行产物：

清理前建议确认没有重要任务仍在运行，也不要手动删除不理解的 daemon 目录。

配置 CLI

查看当前配置：

常见配置项：

这些 key 使用 camelCase：serverUrl、appUrl、organizationId。

配置默认保存在 HiFox 的本机配置目录中。普通用户不需要手动编辑配置文件，优先使用 hifox config show 和 hifox config set。

Profile 是什么？

Profile 是 CLI 的本机配置上下文。不同 profile 可以保存不同登录信息、服务地址、组织上下文或机器连接信息。

常见情况：

默认 profile：你直接使用 hifox login --token 或 hifox setup --token 时使用；

机器 profile：通过 hifox connect machine --install-token ... 创建，通常形如 machine.<local-machine-id>；

指定 profile：使用 --profile 参数切换。

例如：

排查“我明明登录了但 daemon 还是离线”时，要注意当前命令使用的是哪个 profile。机器安装流程创建的 profile 和你手动登录的个人 profile 可能不是同一个。

环境变量

CLI 会优先读取 HiFox 专用环境变量，也兼容部分 APP_* 通用变量。

常用变量：

变量	用途
`HIFOX_TOKEN`	提供个人访问令牌。
`HIFOX_SERVER_URL`	覆盖 API 服务地址。
`HIFOX_APP_URL`	覆盖网页应用地址。
`HIFOX_ORGANIZATION_ID`	指定组织上下文。
`HIFOX_DAEMON_MAX_CONCURRENT_TASKS`	调整 daemon 最大并发任务数。
`HIFOX_AGENT_TIMEOUT`	调整单次 Agent 运行超时时间。
`HIFOX_DAEMON_DEVICE_NAME`	设置机器显示名称。
`HIFOX_AGENT_RUNTIME_NAME`	设置运行时显示名称。

对于 token、server URL 和 organization ID，命令行参数或环境变量通常会覆盖 profile 中的配置。

用 CLI 操作 HiFox 资源

CLI 不只是用来安装 daemon。它也是 Agent、脚本和自动化流程操作 HiFox 的稳定入口。

例如，Agent 在执行外部流程时，可以通过 CLI 把进展写回任务；脚本可以批量创建任务、更新状态、添加评论，或读取组织中的 Agent、项目和仓库信息。

任务操作

常见任务命令包括：

创建任务时，可以继续指定优先级、负责人、项目、父任务、截止日期和附件：

修改任务时，可以更新标题、正文、状态、优先级、负责人、项目、父任务和关注状态：

常用状态别名包括：backlog、todo、in_progress、in_review、done、blocked、cancelled。实际可用状态仍取决于组织和空间里的任务工作流配置。

评论和上下文

Agent 或脚本写回执行结果时，通常使用任务评论：

如果内容来自管道，可以使用标准输入：

也可以读取任务评论，作为自动化或 Agent 的上下文：

JSON 输出

很多资源命令支持 --output json。这对 Agent 和脚本很重要，因为 JSON 比表格输出更适合解析。

例如：

如果命令用于自动化，建议优先使用 JSON 输出，并显式传入组织上下文：

常用命令族

可以用 help 查看当前版本支持的完整子命令：

常见命令族包括：

命令族	用途
`task`	创建任务、查看任务、修改状态、添加评论、管理关注者和任务元数据。
`project`	查看和管理项目。
`agent`	查看和管理 Agent。
`crew`	查看和管理小队。
`automation`	查看和管理自动化。
`organization`	查看和切换组织。
`repo`	查看和管理代码库。
`skill`	查看和管理 Skill。
`chat`	使用 Agent 会话。
`machine`	查看组织中的机器。
`daemon`	管理本机 daemon。
`auth` / `login`	管理 CLI 认证。

不同版本的 CLI 可能会增加或调整命令。以 hifox <command> --help 输出为准。

常见问题

CLI 支持浏览器登录吗？

当前 CLI 登录使用个人访问令牌。先在 HiFox 中创建个人访问令牌，再运行 hifox login --token 或 hifox setup --token。

`login --install-token` 为什么失败？

安装令牌不再用于 login。连接机器时请使用：

daemon 已经启动，为什么 `daemon start` 报错？

如果当前 profile 的 daemon 已经在运行，CLI 不会重复启动。可以用：

确认状态，或者用：

重启 daemon。

机器在线但没有可用运行时怎么办？

检查这台机器上是否安装了支持的 AI 编程工具，并确认它们在 daemon 运行用户的 PATH 中可用。安装后可以重启 daemon：

修改 PATH 后 daemon 还是检测不到工具怎么办？

daemon 可能没有继承你当前终端的最新环境。重启 daemon，并确认工具可以被登录 shell 找到。必要时使用对应的 HIFOX_*_PATH 环境变量指定工具路径。

`auth logout` 会让机器下线吗？

不一定。auth logout 只清除当前 profile 的个人令牌。通过安装令牌连接的机器 profile 使用机器会话，不等同于你的个人登录。要让机器下线，通常需要停止 daemon 或在 HiFox 中删除/断开机器。

自托管地址应该配置哪个？

serverUrl 是 CLI 和 daemon 调用 API 的地址，通常是后端 API 地址。appUrl 是打开网页或认证相关页面时使用的前端地址。

安装前需要准备什么？#

安装 CLI#

macOS / Linux#

Windows#

登录 CLI#

一步完成配置和启动#

使用安装令牌连接机器#

管理 daemon#

检查磁盘占用和清理#

配置 CLI#

Profile 是什么？#

环境变量#

用 CLI 操作 HiFox 资源#

任务操作#

评论和上下文#

JSON 输出#

常用命令族#

常见问题#

CLI 支持浏览器登录吗？#

login --install-token 为什么失败？#

daemon 已经启动，为什么 daemon start 报错？#

机器在线但没有可用运行时怎么办？#

修改 PATH 后 daemon 还是检测不到工具怎么办？#

auth logout 会让机器下线吗？#

自托管地址应该配置哪个？#