#Agent

如果你已经在使用 Claude Code、Codex 等 AI 编程工具，HiFox Agent 不是另一套模型或编程工具。它把一套稳定的工作方式保存下来，再通过电脑上的 Claude Code、Codex 等运行时（Runtime）执行任务。

例如，你可以创建一个“前端修复 Agent”，配置它负责的范围、开始工作前要检查什么、修改后要运行哪些测试、使用哪个代码库和 Runtime。团队之后只需要把合适的任务指派给它，不必每次重新解释整套工作方式。

理解 Agent，需要先区分四个概念：

• 任务：这一次要完成什么，包含目标、上下文、评论和验收要求。
• Agent：应该如何工作，保存职责、指令、技能、代码库和运行设置。
• Runtime：实际执行工作的 AI 编程工具或执行入口，例如 Claude Code、Codex。
• 电脑：Runtime 真正运行的机器，提供代码、凭据、工作目录、网络和计算资源。

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

任务被指派给 Agent
  → HiFox 组合任务上下文和 Agent 配置
  → 派发到 Agent 选择的电脑
  → 电脑上的本地服务启动 Runtime（例如 Claude Code、Codex）
  → Runtime 读取代码、修改文件并运行命令
  → 进展、阻塞和结果写回 HiFox 任务

本页重点介绍如何设计、创建和管理 Agent。完整的电脑连接和 Runtime 状态见 电脑，完整执行过程见 Agent 如何执行任务。

#系统提供的助手

除了你自己创建的 Agent，HiFox 还会提供两类内置助手。它们不是从「创建 Agent」表单建出来的，也不会出现在普通 Agent 列表里。

• 小助手：每个人在每个组织里有一个。它出现在侧栏「我的任务」下方，第一次打开时自动创建。没有设置页，名称和指令由系统管理，只支持直接对话。Runtime 在对话输入区选择，不属于任何空间。
• IM 任务助手：每个空间在飞书、钉钉、企业微信、Slack 上各可以有一个。从对应的外部应用集成页绑定，选择 Runtime，并按该 IM 的方式完成机器人绑定。绑定后可填写附加提示词。它只在对应 IM 里工作，不能在站内私聊或 @，也不会出现在普通 Agent 列表或处理人选择器里。需要把某个自建 Agent 接到 IM 时，继续用该 IM 的 Agent 机器人，而不是任务助手。

把鼠标移到普通 Agent 的头像上，悬停卡片里可以选择打开设置。内置助手没有这项入口。

#什么时候创建 Agent？

当一类工作具有稳定的职责或工作方式时，适合创建专门的 Agent。例如：

• 前端 Agent：处理 UI 修复、组件开发和前端测试；
• 测试 Agent：分析失败用例、补充测试并整理复现步骤；
• Review Agent：按团队标准检查代码质量、安全风险和测试覆盖；
• 文档 Agent：维护产品文档、术语和发布说明；
• 专项助理 Agent：拆解任务、总结进度并识别阻塞。

不要急着创建一个“什么都能做”的 Agent。职责越明确，团队越容易知道该把什么任务指派给它，它也越容易使用一致的方法完成工作。

如果要求只针对一次工作，直接写进任务；如果是一套会被多个 Agent 复用的流程，更适合整理成技能。

#Agent 包含哪些配置？

Agent 本身不是电脑，也不是代码仓库。它是一组“如何工作、在哪里工作”的配置，通常包括：

模型由 Runtime 决定。Agent 默认跟随所选 Runtime 的模型，也可以在 模型 行从 Runtime 上报的模型列表里另选；Runtime 在启动参数里固定了模型时，这一行只读。模型行还会在模型公布思考深度时提供思考深度选择，默认项跟随该模型自己的默认深度，模型没有公布深度时不显示这个入口。需要更换模型时，也可以在 Agent 或 Runtime 的自定义参数里指定，例如「指定模型：模型名」；OpenClaw 不会用 --model 选择模型。也可以继续修改 Runtime 或电脑上的工具配置。

#Agent 类型和空间用途

创建 Agent 时可以选择工作类型：

• 代码开发：适合需要代码库、工作目录和开发工具的任务；
• 日常办公：适合调研、整理、写作和其他不需要代码环境的工作；
• 设计创意：目前仍不可用，开放时间以产品界面为准。

代码开发还有三种工作方式（名称以线上为准）：

• Agent 自动拉取 Git 代码仓库：每个任务使用独立的 Git worktree，适合团队协作；
• 手动指定代码所在目录：使用电脑上已有的代码目录，适合超大代码库等场景；
• 不需要代码库：适合临时生成代码、不需要 Git 代码库的场景；选择后没有额外输入项。

未提供代码来源时，会提示：请添加 Git 代码库，或将工作方式改为“手动指定代码所在目录”或“不需要代码库”。选了手动指定目录但未填写路径时，会提示：请输入代码所在目录，或修改为其他工作方式。切换工作方式后，原来的错误提示会消失。

首次在空间中创建 Agent 时，HiFox 会根据空间用途给出默认类型：软件开发空间默认选择代码开发，其他空间用途默认选择日常办公。你手动选择过类型后，后续创建流程会记住你的选择。

日常办公模式不会继续校验或提交代码开发相关的代码库、路径等配置；需要处理代码时，请切换回代码开发并提供有效的代码来源或工作目录。Agent 类型不代表额外权限，成员仍需具备对应空间、电脑、Runtime 和资源的访问权限。

#在列表里找到自己的 Agent

Agent 页面顶部提供 全部 / Agent / 小队 / 我的 四个视图。选择 我的 时只列出你创建的 Agent 和小队，其他人的会被过滤掉。

列表按置顶和所属空间分成若干分组，每个分组都可以折叠、展开，不常看的分组收起来即可。

常用的 Agent 和小队可以置顶：在列表行上选择 置顶，置顶项集中显示在列表顶部的 置顶 区；用同一处的 取消置顶 放回去。

视图切换、折叠和置顶都是你个人的列表偏好，不会改变 Agent 本身的可见性、权限，也不会影响别人的列表顺序。空间里的 Agents 列表也有同样的筛选、搜索和置顶能力，并且置顶互通：在一处置顶，「全部 Agents」和所在空间的列表会同时生效。列表里完全找不到某个 Agent 的原因见下文「为什么某个 Agent 在列表里找不到？」。

#创建一个可用的 Agent

一般流程是：

1. 确定 Agent 的稳定职责；
2. 填写便于团队判断用途的名称和描述；
3. 编写 Agent 指令；
4. 选择所属空间和可见性；
5. 选择可用的电脑和 Runtime；
6. 按需绑定技能、Git 仓库和运行配置；
7. 使用一个低风险任务验证它能否正常执行和回写结果。

#名称和描述写给团队看

创建时，名称输入框下方会推荐一组名称，点击即可填入；每次打开创建窗口会重新生成，也可以换一批。国内版会推荐 8 个名称，并提供 HiFox 取名工具入口；国际版不展示该入口。

名称应该让人一眼知道 Agent 的主要用途。描述则说明适合指派什么工作，以及不适合处理什么。

例如：

负责处理前端 UI 小修复和组件测试补齐。适合范围明确、可以独立验证的前端任务；涉及整体视觉方案或跨端架构调整时需要先由成员确认。

相比“开发 Agent”或“万能 Agent”，这样的描述更容易帮助团队正确选择处理人。

#指令写给 Agent 执行

指令编辑器是所见即所得的：编辑时看到的就是最终的样子，不需要记 Markdown 语法。

指令会进入 Agent 的任务上下文，适合描述长期稳定的工作方式：

• 它负责什么、不负责什么；
• 接到任务后先阅读或检查什么；
• 什么情况下需要先提问；
• 修改代码后运行哪些检查；
• 遇到失败或缺少权限时如何处理；
• 最终需要汇报哪些内容；
• 哪些操作不能自行执行。

例如：

你负责处理小型前端修复。开始前先阅读任务描述、最近评论和相关代码；只有不同理解会明显改变实现时才提问。修改范围保持最小，完成后运行最接近的组件测试，并在任务中说明改动内容、验证结果和仍存在的风险。不要隐藏失败的检查。

不要把某个单次任务的具体需求长期写进 Agent 指令，否则后续不相关任务也会携带这些内容。

指令卡片还提供自动翻译为英文开关（卡片上的语言图标，悬停打开）。开启后，保存的指令会自动翻译成英文，Agent 运行时优先使用译文——多数模型对英文指令的理解更好；译文单独保存，原文不会被修改，每次修改指令后会自动重新翻译。译文尚未就绪时会自动回退用原文，不会阻塞任务。悬停浮层里可以查看翻译状态和译文。

#用低风险任务验证

创建完成后，建议先指派一个只读任务：

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

这个任务可以同时验证：

• Agent 是否选择了正确的电脑和 Runtime；
• Claude Code、Codex 等工具能否真正启动；
• Agent 是否获得了预期的任务上下文和指令；
• 电脑能否访问代码库和工作目录；
• Agent 能否把结果写回任务。

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

#电脑、Runtime 和模型

Agent 的执行目标由电脑和 Runtime 共同决定：

• 电脑提供操作系统、代码、凭据、目录、网络和计算资源；
• Runtime 决定实际启动 Claude Code、Codex 或其他执行入口；
• Agent 保存对这个 Runtime 的使用方式和任务配置。

电脑在线并不等于 Agent 一定能工作。在线只表示本地服务心跳正常；只有 Agent 所选 Runtime 处于可用状态，任务才具备启动条件。

创建或重新绑定 Agent 时，可以选择离线电脑上的离线 Runtime，方便先完成配置。尚未检测到、检测失败、已卸载或不在可选范围内的 Runtime 仍不可选。本机电脑会排在前面，并带「（本机）」标记。默认优先选在线 Runtime；没有在线项时，会回退到本机离线 Runtime。创建 Agent 不会自动启动电脑。导入或「立即运行」等入口仍只提供在线 Runtime。

选择 Runtime 时，列表里可能看得到某台电脑上的 Runtime，但若该 Runtime 所在电脑不允许用于当前 Agent 所选空间，该项会置灰，不能提交。提示会说明当前空间不可用，并带上空间名称。这和电脑离线不是同一回事：离线是连接状态，空间不可用是这台电脑对当前空间的使用范围。

列表里不可用的电脑或 Runtime，悬停后可以通过 去查看 打开对应详情。选择器主要列出已经在这台电脑上可用的 Runtime，不代表产品只支持这些；可以通过 支持更多 Runtime 打开电脑详情，查看并安装其他支持的 Runtime。去查看是打开已列出但不可用的那一台；支持更多 Runtime 是发现尚未连接的选项。

一台电脑可以服务多个 Agent，但任务能否立即运行还会受到电脑并发、Agent 并发和工作目录占用情况影响。连接、状态和排障方法见 电脑。

#把任务指派给 Agent

在任务的处理人中选择 Agent 后，它会成为这个任务的执行者。

• 如果任务处于 Todo、In Progress 或其他可执行状态，HiFox 会尝试开始运行；
• 如果任务仍在 Backlog，Agent 会等待，不会立即开始；
• 如果电脑、Runtime、并发或工作目录暂时不可用，任务会排队；
• 后续要让 Agent 继续处理时，在任务评论里 @ 该 Agent，或直接进入任务上的对话。普通评论不会自动触发处理人 Agent。

也可以从 Agent 详情选择指派任务。在这里可以搜索该 Agent 所属空间中的已有任务，或直接在同一空间新建任务。这个入口只提供当前成员有权访问、尚未归档的同空间任务；跨空间、已归档或无权访问的任务不会出现在选择中。只有未归档、非小队专属且当前具备执行条件的 Agent 才能用于此入口。

通过任一入口指派时，Agent 会作为执行处理人加入任务，不会移除已有的人员处理人。点击指派任务也不代表任务一定立即开始：任务状态、电脑和 Runtime 可用性、并发以及工作目录仍会决定任务是启动还是排队。

执行过程中，任务会保留 Agent 的进展、阻塞、失败、结果和对话记录。团队不需要到某个人的本地终端里寻找过程和结论。

任务状态和 Agent 工作状态是两套概念。任务可以处于 In Progress，而 Agent 运行可能仍在排队；Agent 也可能已经完成一轮运行，但任务仍需要成员 review 或继续推进。完整状态和触发方式见 Agent 如何执行任务。

#代码库和凭据

Agent 可以绑定 Git 仓库：

• 如果 Agent 绑定了仓库，优先使用 Agent 自己的仓库配置；
• 如果 Agent 没有绑定仓库，通常使用任务所属空间配置的 Git 仓库；
• 如果两边都没有配置，Agent 可能能读取任务，但无法进入代码目录完成代码工作。

真正执行 clone、git、gh、构建和测试命令的是 Agent 所在的电脑。电脑上的 Git 凭据、目录权限和必要工具必须可用。

不要把密码、Token、API Key 或私钥写进 Agent 指令、任务描述或评论。完整配置方式见 连接代码库。

#技能：复用团队工作方法

技能用来保存可以被多个任务或 Agent 复用的流程、规范和专业知识。例如：

• 代码 review 清单；
• 发布检查步骤；
• 文档写作规范；
• 前端组件测试流程；
• 故障排查方法。

如果同一套要求会反复出现，把它整理成技能比复制进多个 Agent 指令更容易维护。Agent 可以绑定多个技能，但不要添加大量无关内容，否则会增加上下文噪音。

技能的创建、导入和维护方式见 技能。

#运行设置

打开 Agent 设置，进入 运行设置。这里控制 Agent 如何使用电脑资源，主要包括：

• 默认工作目录：选择创建临时目录，或指定电脑上的已有目录；
• 最大并发数（执行指派的任务）：Agent 同时可以处理多少个被指派的任务；
• 最大并发数（聊天对话）：Agent 同时可以处理多少个对话；
• 单任务最大运行时长：避免任务无限运行；
• 环境变量和启动参数：为 Runtime 或任务命令提供额外配置。

聊天并发可以和任务并发分开：

• 默认：独立计数；
• 共享任务并发：与「执行指派的任务」使用同一个额度；
• 手动输入：单独指定聊天并发。

总并发仍受电脑上限限制；可以从运行设置打开电脑的并发设置。具体选项名和默认额度以线上为准。

环境变量和自定义参数在 Agent 设置或 Runtime 详情中以表格添加、修改和删除；未配置时用「添加」。每行填写一个参数及其值。粘贴多个参数会自动分行；包含空格的值请用引号包住。保存时会保留你输入的换行，不会按空格自动折行。环境变量值默认隐藏，需要时再显示。已检测 Runtime 的执行程序、默认附加参数和默认环境变量会提供基础启动配置。Agent 为同一个启动参数或环境变量设置的值优先于 Runtime 默认值。

#选择工作目录

默认工作目录可以是 创建临时目录，或 指定已有目录。完整说明见 Agent 工作目录。

选择指定已有目录并保存 Git 目录时，会出现 如何使用这个目录：

确认按钮是 确定。不是 Git 目录时，只能直接在该目录运行。隔离运行不要再按多目录设置来理解。

一般建议优先选择创建临时目录，或指定目录后的隔离运行。直接在原目录运行不会为每个任务创建独立代码副本，同一目录一次只能跑一个任务，其余排队。

默认并发规则：

• 指定已有目录且直接运行：默认并发等于已配置的目录数；
• 创建临时目录，或指定目录后隔离运行：默认并发是电脑并发的 50%。

可以手动调整并发，但不要盲目调高。更高并发会增加 CPU、内存、磁盘、网络和 Runtime provider 的压力；如果手动值高于指定目录数量，界面也会提示写入冲突风险。

#所属空间和可见性

每个 Agent 必须且只属于一个空间，只能用于该空间中的任务。

Agent 有两种可见性：

• 私有：只有 Agent 所有者可以看到和使用；
• 共享：所属空间中有访问权限的成员可以看到和使用。

可见性会影响成员能否找到 Agent、把任务指派给它、与它对话，或在任务评论里 @ 它。任务只能选择与自己位于同一空间、且当前成员有权使用的 Agent。

部分 Agent 可能被设置为小队专属 Agent。这类 Agent 只能在所属小队中被调用，不会出现在普通 Agent 列表、处理人选择器或独立对话入口。详见 小队专属 Agent。

#Agent 状态和排障

Agent 列表和详情页会展示可用性、当前工作负载和最近运行。常见状态包括：

• 空闲：当前没有任务在运行；
• 工作中：正在执行任务；
• 受阻：运行遇到需要处理的问题；
• 错误：最近运行出现错误；
• 离线：电脑或 Runtime 当前不可用。

Agent 状态和单次运行状态不同。即使 Agent 在线，任务也可能因为并发已满或指定目录被占用而排队。

如果 Agent 没有开始，建议按以下顺序检查：

1. 任务是否仍在 Backlog；
2. Agent 所选电脑是否在线；
3. 所选 Runtime 是否可用；
4. 代码库、凭据和工作目录是否可访问；
5. 电脑或 Agent 并发是否已满；
6. 对话记录中是否有明确错误或等待原因。

#运行历史和消耗

Agent 详情可以展开为全屏，页内导航在 设置 和 运行历史 之间切换。打开 Agent 详情的菜单里也有 查看运行历史 入口。

运行历史按行列出每一次运行：

• 这次运行的状态；
• 来源：任务、对话、自动化还是工作流；
• 触发来源：是谁调用的；为空时显示「未知」，自动化触发显示「自动化」；
• 运行时间和这次运行消耗的 Token。

点开某一行只在右侧再开一层抽屉，继续往下点也不会层层叠加。列表拉到底可以 加载更多。

详情概览上的 Token 是这个 Agent 历史上全部消耗的合计，没有用量数据时显示「—」。

#与 Agent 对话

除了把任务指派给 Agent，也可以直接与 Agent 对话。

对话适合临时询问、调研、解释和讨论方案；任务适合需要跟踪、指派、执行和验收的工作。如果对话中形成了明确行动项，建议创建任务并把结论带过去。

独立对话、任务中的 Agent 对话和任务评论并不是同一套记录。具体区别和使用方式见 与 Agent 对话。

#归档和恢复 Agent

不再使用的 Agent 可以归档。归档后：

• 不能再被指派新任务或在评论中提及；
• 正在执行的工作会被取消；
• 历史任务、评论和对话记录仍会保留。

归档前，先确认是否仍有运行或排队任务，以及自动化或小队是否仍依赖它。

需要恢复时，进入 Agent 列表的更多菜单，打开已归档 Agent，找到目标 Agent 后选择恢复。恢复后，它会重新出现在列表中；当空间权限、电脑和 Runtime 条件满足时，可以再次使用。

#最佳实践

• 按稳定职责创建：让一个 Agent 对应一类清晰工作，而不是覆盖所有场景。
• 描述写用途，指令写方法：描述帮助人选择，指令帮助 Agent 执行。
• 单次要求放任务：不要让临时需求长期污染 Agent 指令。
• 复用流程放技能：让团队维护一份规范，而不是复制多份 prompt。
• 先用只读任务验证：确认 Runtime、仓库、权限和结果回写都正常后，再执行写操作。
• 逐步提高并发：先确认电脑和 Runtime 能稳定处理当前负载。

#常见问题

#Agent 的模型和思考深度怎么设置？

Agent 默认跟随所选 Runtime 的模型，也可以在 模型 行另选一个。模型行会为支持的 Runtime 提供思考深度选择，选定的级别在新建会话时应用，续聊时也会重新应用：

• Runtime 不接受所选深度时，运行会明确报错，而不是页面上显示一个值、运行时仍用默认深度；
• 通过自定义参数指定思考深度时，如果 Runtime 在首次请求前没能应用，这次运行会停止并明确报错；
• 模型没有公布可选深度时不显示这个入口，按 Runtime 自身的默认行为执行。

需要更换模型时，可在 Agent 或 Runtime 的自定义参数里指定，例如「指定模型：模型名」。OpenClaw 不会用 --model 选择模型。也可以继续修改 Runtime 或电脑上的工具配置。

#Agent 没有开始运行怎么办？

先确认任务不在 Backlog，再检查电脑是否在线、Runtime 是否可用、代码库和凭据是否正确，以及并发或工作目录是否已满。对话记录通常会显示具体等待或失败原因。

#什么时候应该新建一个 Agent？

当一类工作有稳定职责、固定指令、特定代码库或固定技能时，适合创建专门 Agent。只针对一次任务的要求应直接写在任务中。

#Agent 和小队有什么区别？

Agent 是单个 AI 队友，适合职责清楚、可以独立完成的工作；小队由队长 Agent 协调多个 Agent 或成员，适合需要拆解、分工和汇总的复杂任务。详见 小队。

#为什么某个 Agent 在列表里找不到？

它可能已归档、属于其他空间、当前成员没有使用权限，或者被设置为小队专属 Agent。小队专属 Agent 只能在对应小队中使用。小助手和 IM 任务助手也不会出现在普通 Agent 列表里。