守护进程与运行时

智能体不在 AACWorkflow 服务器上运行——它们跑在你自己的机器上。

在 AACWorkflow 里，智能体不在我们的服务器上运行——它们跑在你自己的机器上，由一个叫守护进程（daemon）的小程序调用本地安装的 AI 编程工具。AACWorkflow 服务器只做协调：存 issue、排任务、派发给正确的运行时（runtime = 守护进程 × 一款 AI 编程工具）。

这个结构带来 AACWorkflow 和 Linear / Jira 最大的差别：你的 API 密钥、工具链、代码目录都留在本地，AACWorkflow 服务器一个都看不到。"我的智能体不工作"类问题几乎都是本地问题——守护进程没启动、某款 AI 工具没装、密钥过期——请先从本地查起；定位指引见故障排查。

启动守护进程

守护进程是 AACWorkflow CLI 的一部分。装好 AACWorkflow CLI 后，在自己机器上跑：

aacworkflow daemon start

启动后它会做四件事：

读取你登录时保存的凭证
探测本机 PATH 上已安装的 AI 编程工具（内置支持 16 款：Antigravity、Claude Code、CodeBuddy、Codex、Cursor、Copilot、Hermes、Kimi、Kiro CLI、OpenCode、OpenClaw、Pi、Qoder、Trae CLI、DevEco Code、Grok）
向服务器注册自己，以及每款检测到的工具对应的运行时
持续每 30 秒轮询一次是否有任务要领，每 15 秒发一次心跳

常用命令：

命令	作用
`aacworkflow daemon start`	启动（默认后台，加 `--foreground` 前台运行）
`aacworkflow daemon stop`	停止
`aacworkflow daemon restart`	重启
`aacworkflow daemon status`	查看状态
`aacworkflow daemon logs`	查看日志（加 `-f` 跟随）

完整 CLI 参考见 CLI 命令速查。

**桌面应用自带守护进程。**用桌面应用就不必手动 aacworkflow daemon start——它启动时会自动拉起守护进程。哪种方式更适合你的工作流，详见桌面应用页面。

为什么一台机器会有多个运行时

运行时不是一个服务器，也不是一个容器——它是「守护进程 × 一款 AI 编程工具」的组合。举例：你在一台 MacBook 上启动守护进程，本机装了 Claude Code 和 Codex；你是两个工作区的成员。那么 AACWorkflow 会注册 4 个运行时：

Rendering diagram…

关键的点：

一个守护进程可以对应多个运行时——装了多款工具、加入了多个工作区，每个组合就各一个
同一个守护进程在同一个工作区同一款工具上只会有一条运行时——重启守护进程不会产生重复记录
AACWorkflow 界面的 Runtimes 页面列的就是这些行

自定义运行时配置

内置 provider 探测覆盖常见工具；如果团队的 AI CLI 兼容 AACWorkflow 已支持的协议族、但需要不同的启动命令，可以定义自定义运行时配置（custom runtime profile）。常见场景包括：给 Codex 套一层团队内部 wrapper、固定使用某个版本的可执行文件，或者为团队 CLI 预设模型参数。

如果只是按默认命令使用 Claude Code、Codex、Kimi 或其他内置 provider，不需要创建自定义配置；守护进程会自动探测它们。

创建前确认

至少在一台运行 AACWorkflow 守护进程的机器上安装好自定义命令，并确认同一条命令能在这台机器的终端中运行。
确认这个工具实现了界面中某一种基础协议。选择协议族只是告诉 AACWorkflow 如何与进程通信，并不能让不兼容的 CLI 自动变得兼容。
只有工作区所有者或管理员可以创建、编辑和删除自定义运行时配置。

从 Runtimes 界面创建

打开 运行时（Runtimes），进入已经安装该命令的机器。
点击添加自定义运行时。
选择这个命令实际实现的基础协议类型。
填写显示名称，以及你会在终端中执行的命令；命令可以带固定参数。建议补充用途描述，方便其他成员识别。
点击创建运行时。

配置定义属于整个工作区，会同步到所有已连接的守护进程；每台机器只有在本机能找到对应命令时，才会注册自己的运行时。从哪台机器发起创建，该机器就会先显示一条临时的注册中记录。如果它迟迟没有变成在线，请确认命令已安装，并且该机器的守护进程能找到它。

创建配置不会自动安装 CLI、完成登录，也不会把命令复制到其他机器。每一台需要提供该运行时的机器，都必须单独安装并登录底层工具。

使用 CLI 管理

同一组工作区配置也可以通过 CLI 管理：

aacworkflow runtime profile list
aacworkflow runtime profile create --display-name "Composer" --protocol-family codex --command-name agent
aacworkflow runtime profile update <profile-id> --command-name agent
aacworkflow runtime profile delete <profile-id>

内置和自定义运行时都显示在同一份机器列表里。打开自定义运行时所在行的操作菜单，即可编辑或删除配置。删除配置后，各机器上由它注册的运行时实例会在守护进程同步后移除；如果仍有智能体依赖它，删除操作可能会被阻止。

这里填写的是 argv 风格命令，不是 shell 字符串。AACWorkflow 存的是可执行文件名和固定参数，守护进程会直接用 exec.Command(command_name, fixed_args...) 启动。支持普通参数、引号和反斜杠转义；不支持管道、重定向、&&、;、反引号、$VAR / $(...) 展开。需要 shell 行为时，用 wrapper script 包一层。目前命令和参数的解析入口在 Runtimes UI；CLI 的 profile 命令负责管理 profile 记录和本机路径覆盖。

如果桌面应用拉起的守护进程找不到你在终端里能运行的命令，可以在这台机器上固定绝对路径：

aacworkflow runtime profile set-path <profile-id> --path /abs/path/to/agent
aacworkflow runtime profile unset-path <profile-id>

修改 profile 的命令或参数后，已开始的任务仍使用启动时的参数；守护进程重新注册后，新领取的任务才会使用新配置。混合版本部署时，建议先升级 server，再逐步升级 daemon：fixed_args 的录入在 server 侧 Runtimes UI，failed_profiles 注册报告也由 server 展示。旧组件可能会忽略自己不认识的字段，而不是明确报错；先升 server 能让 rollout 更可观察。

云端运行时即将开放，目前处于等待名单阶段。上线后，你无需在本地运行守护进程，即可在 AACWorkflow Cloud 上直接执行智能体任务。在下载页面登记邮箱以获取通知。

运行时什么时候被判定为离线

AACWorkflow 用心跳判断运行时是否在线。三个关键数字：

事件	阈值
守护进程心跳频率	每 15 秒
标记为失联	超过 45 秒没心跳（漏了 3 次）
自动删除	失联且无关联智能体超过 7 天

失联不是永久的——守护进程只要再次发出心跳就立刻回到在线，运行时记录也会保留。重启守护进程不会丢运行时。

失联的运行时上正在跑的执行任务会被标记为失败（失败原因 runtime_offline）。对可重试的来源（issue、chat），AACWorkflow 会自动重新排队；Autopilots 触发的任务不自动重试。详见执行任务 → 哪些失败会自动重试。

一次能并发跑多少任务

AACWorkflow 对并发有两层限额：

守护进程层：默认 20 个执行任务并发（环境变量 AACWORKFLOW_DAEMON_MAX_CONCURRENT_TASKS 可调）
智能体层：每个智能体默认 6 个执行任务并发（智能体配置里改）

两层中更紧的那层生效。如果你的守护进程已经在跑 20 个任务，即使某个智能体还有余量，新的任务也要等。

如果你看到执行任务卡在 queued 状态不 dispatched，通常就是这两层里某一层打满了。

守护进程崩溃后，没跑完的任务会怎样

守护进程崩溃或被强行结束时，它领走的执行任务会停在 dispatched 或 running 状态。下次启动时，守护进程会告诉服务器：「这些任务不是我的了，请标记失败。」服务器把它们改成 failed，失败原因 runtime_recovery——对可重试的来源，任务自动重新排队。

即使这一步因网络问题没完成，还有每 30 秒一次的服务器端扫描作为后备：超过 45 秒没心跳的运行时会被统一标记为失联，上面的任务也一并回收。

Agent 不工作怎么排查

遇到「我的智能体不工作」类问题，先过一遍这三步：

跑 aacworkflow daemon status，确认守护进程在运行且在线
跑 aacworkflow daemon logs -f，看是否有错误
去 AACWorkflow 界面的 Runtimes 页面，确认你的运行时显示「在线」

更多场景见 Troubleshooting。

下一步

执行任务 —— 守护进程领到任务后，它的完整生命周期
Providers Matrix —— 16 款 AI 编程工具的能力差异对照

本页目录