守护进程与运行时
了解 Multica 如何连接电脑、发现 AI 编程工具并 task。
Multica 负责记录和协调工作，连接的电脑负责执行。电脑上的守护进程（daemon）领取 task，再调用本机安装的 AI 编程工具。
概念区分
- 守护进程是运行在一台电脑上的 Multica 后台程序。它负责连接服务器、发现本机工具、领取 task 和回传结果。
- 运行时代表一个工作区可以使用的具体执行环境。它对应一台电脑，以及这台电脑上的一款 AI 编程工具或自定义运行时配置。
例如，一台电脑同时安装了 Claude Code 和 Codex，并连接两个工作区。守护进程会分别为两个工作区注册 Claude Code 和 Codex 运行时。重启守护进程会更新原有记录，不会为同一个组合不断创建新运行时。
执行位置与数据边界
本地运行时调用的 AI 编程工具、这些工具自己的登录凭据，以及本地代码目录都留在连接的电脑上。Multica 服务器不会代替本地工具执行命令，也不会自动上传整个工作目录。
为了让团队能够协作，服务器会保存任务、评论、智能体配置、task 上下文、执行记录和智能体写回的结果。这些内容可能包含智能体主动读取并写入回复的代码片段或其他项目上下文。
智能体的自定义环境变量保存在服务器侧，并在执行时发送给运行时。不要把"本地执行"理解为所有 secret 都只存在本机；自定义环境变量和 MCP 配置保存在服务器侧，展示受敏感信息规则限制。
启动守护进程
使用 Multica Desktop 时，应用会自动启动守护进程，不需要额外运行命令。
使用 Web、远程电脑或无界面环境时，先安装 Multica CLI，再运行：
multica daemon start守护进程默认在后台运行。常用命令如下：
| 命令 | 作用 |
|---|---|
multica daemon status | 查看守护进程和连接状态 |
multica daemon logs -f | 持续查看日志 |
multica daemon restart | 重启守护进程并重新检测本机工具 |
multica daemon stop | 停止守护进程 |
multica daemon start --foreground | 在当前终端中运行，便于调试 |
如需把 task 工作目录放到其他磁盘，可用 multica config set workspaces_root <path> 为当前 profile 持久化根目录，也可在 daemon start 或 daemon restart 中传入 --workspaces-root <path>。flag 的优先级高于 MULTICA_WORKSPACES_ROOT，环境变量又高于 profile 配置。修改根目录不会迁移已有的 task 目录。
启动时，守护进程会检测 PATH 中受支持的 AI 编程工具，并为你有权连接的工作区注册运行时。如果一款工具刚刚安装或登录，重启守护进程即可重新检测。
守护进程至少需要检测到一款内置支持的 AI 编程工具才能启动。安装方法和可执行文件名见安装 AI 编程工具。
派发与在线状态
运行时注册后会持续保持连接。新 task 入队时，服务器会通知对应守护进程；守护进程也会定期轮询，作为连接中断后的补充。因此运行时在线且有空闲容量时，task 通常会立即开始。
守护进程每 15 秒发送一次心跳。服务端综合心跳与连接状态判断运行时是否在线；守护进程意外退出后，最迟通常会在约 3 分钟内显示为离线。
运行时离线时：
- 已经排队的 task 会等待运行时恢复，只有当它心跳缺席超过重连宽限期且该 task 自己也已排队满这么久时才会失败；所以运行时只是忙的话积压会一直保留，指派给已离线运行时的工作也仍然有完整一个宽限期可以等待。
- 正在执行的 task 会失败；符合条件的任务或对话 task 可以自动重试。
- 守护进程重新启动后，会重新注册运行时，并回收上一次没有正常结束的 task。
- 离线超过 7 天且没有任何智能体（包括已归档的）绑定的运行时，会被自动清理。
详细状态和重试规则见Task。
并发限制
一台守护进程默认最多同时执行 20 条 task；每个智能体默认最多同时执行 6 条。实际并发取两者中的较小值。
达到上限后，新 task 会继续排队。你可以在智能体设置中调整单个智能体的并发数，也可以通过 MULTICA_DAEMON_MAX_CONCURRENT_TASKS 调整整台电脑的上限。并行执行会同时占用机器性能、工具账号额度和同一工作目录。
私有与公开
本地运行时默认是私有的：只有运行时所有者可以在它上面创建智能体。工作区的 owner、admin 也不例外——运行时是别人的电脑，在上面跑智能体消耗的是对方的机器和工具凭据。
只有运行时所有者可以把它改为公开——管理员可以重命名或删除运行时，但要不要共享由所有者决定。公开后，工作区中的其他成员也可以选择这条运行时；这不会分享底层 AI 编程工具的登录凭据，只是允许成员把智能体的 task 路由到这台电脑。
自定义运行时配置
如果团队使用内部 wrapper、固定版本的可执行文件，或需要为一款兼容工具追加固定参数，可以创建自定义运行时配置。
自定义配置不会增加新的通信协议。创建时仍需选择一种 Multica 已支持的协议族（工具的对接协议类型，见 AI 编程工具对照）；命令本身必须与该协议兼容。
Task 运行时环境
守护进程启动智能体 task 时，会把 task 上下文注入运行时进程。这些值由守护进程管理；智能体的自定义环境无法覆盖任何 MULTICA_ 变量或 task 临时目录变量。
下表列出自定义运行时目前可以使用的变量。它不是完整清单，也不是有版本保证的 API。集成只能依赖标为集成契约的 5 个变量；其余变量仅供参考，后续可能变化。
| 变量 | task 中的值 | 稳定性 |
|---|---|---|
MULTICA_TOKEN | task 级 mat_ API 凭据 | 集成契约 |
MULTICA_TASK_ID | 当前 task 的 ID | 集成契约 |
MULTICA_AGENT_ID | 被指派智能体的 ID | 集成契约 |
MULTICA_WORKSPACE_ID | task 所属工作区的 ID | 集成契约 |
MULTICA_SERVER_URL | 守护进程选定的 Multica 服务地址 | 集成契约 |
MULTICA_TASK_CONFIG_ROOT | 私有的 task 本地 Multica CLI 配置根目录 | 仅供参考 |
MULTICA_TASK_WORKSPACES_ROOT | 守护进程管理的 task 工作区根目录 | 仅供参考 |
MULTICA_AGENT_NAME | 被指派智能体的显示名称 | 仅供参考 |
MULTICA_DAEMON_PORT | 本地守护进程的健康检查/API 端口，供 multica repo checkout 等仅限 task 的命令使用 | 仅供参考 |
MULTICA_TASK_SLOT | 守护进程全局并发池中的槽位，可用于 GPU 等按槽位编号的资源 | 仅供参考 |
TMPDIR | 当前 task 的私有临时目录；也会以 TMP 和 TEMP 提供给跨平台工具 | 仅供参考 |
使用 MULTICA_TOKEN 发起请求时，作者身份由服务端决定；任务评论等写入操作会归属到被指派的智能体和当前 task。令牌的完整绑定关系、权限、归属方式、最长 24 小时的有效期和清理规则见智能体执行的临时令牌。
这些值存在于运行时进程的实际环境中。运行时启动的任何子进程默认都会继承全部变量，包括 MULTICA_TOKEN。如果子进程不应持有该凭据，必须显式移除；不要假定进程之间存在并没有的隔离。反过来，有些工具会过滤自己的子进程环境，因此可能需要显式放行变量。例如，Codex 的 shell 工具会丢弃名称中含有 TOKEN、KEY 或 SECRET 的变量，所以守护进程会安装托管的 shell 策略，放行所需的 task 变量。令牌只能存在于进程环境中，不得写入 prompt、日志、仓库文件或持久配置。子进程与父 task 共享身份和权限，不会获得新的独立作用域身份。
创建配置
只有工作区 owner 和 admin 可以创建、修改或删除自定义运行时配置：
- 打开 运行时，进入已经安装该命令的电脑。
- 点击添加自定义运行时。
- 选择命令实际兼容的协议族。
- 填写名称、命令和固定参数，然后保存。
配置会在工作区内共享。每台已连接电脑会自行查找这个命令；只有能在 PATH 中解析到它的电脑才会注册对应运行时。创建配置不会自动安装命令，也不会替其他成员完成工具登录。
这里填写的是可执行文件和参数，不是 shell 脚本。可以使用普通参数、引号和反斜杠转义，但不能使用管道、重定向、&&、;、反引号或环境变量展开。需要这些行为时，把它们放进 wrapper script，再把该脚本作为命令填写。
参数的排列顺序
命令字段里填写的内容会紧跟在可执行文件之后，排在 Multica 追加的参数之前：
<你的命令> <你的固定参数> <Multica 的协议参数> <Agent 的自定义参数>带子命令的 wrapper 正是依靠这个顺序才能工作。如果命令是 ccms start q36，工具会先看到 start q36，在 Multica 的 -p 等参数到达之前完成子命令选择——这类 wrapper 只接受这一种顺序。
此前这里填写的参数是追加在最后的。多数 flag 形式的命令在两种位置下解析结果相同，但并非全部——如果某个命令区分全局 flag 和子命令 flag，它就会在意 flag 的位置。如果你已经配置了带固定参数的 profile，升级后请跑一个 task 确认它仍能正常启动。
另有两点需要注意：
- 冲突时以 Multica 的值为准。 如果固定参数设置了 Multica 也会设置的 flag，Multica 的值排在后面并最终生效。最典型的是：在 Agent 上选择的模型会覆盖 profile 里固定的
--model。若要为所有人固定模型，请把 Agent 的模型字段留空。 - 协议关键 flag 会被忽略。
-p、--output-format、--input-format、--permission-mode以及其他协议族的对应 flag 会从固定参数中被剔除，因为覆盖它们会切断 daemon 与工具之间的通信。子命令和其他位置参数始终原样传递。
如果 Desktop 启动的守护进程找不到终端里能够执行的命令，可以为当前电脑设置绝对路径：
multica runtime profile set-path <profile-id> --path /absolute/path/to/command移除路径覆盖：
multica runtime profile unset-path <profile-id>修改配置只影响之后领取的 task。删除配置前，需要先处理仍绑定在对应运行时上的活动智能体。只删除某台电脑上的运行时实例并不会删除配置，运行中的守护进程还会重新注册它。
运行时离线的排查
按以下顺序检查：
- 运行
multica daemon status，确认守护进程已经启动。 - 运行
multica daemon logs -f，查看登录、网络或工具检测错误。 - 在同一运行环境中执行
command -v <工具命令>，确认守护进程能够找到它。 - 打开 Multica 的运行时页面，检查目标电脑和对应的 AI 编程工具是否显示在线。
- 工具刚安装、路径刚修改或配置刚更新时，运行
multica daemon restart。
仍未解决时，参见故障排查。
接下来
- 安装 AI 编程工具 — 安装并验证一款受支持的 AI 编程工具。
- AI 编程工具对照 — 比较模型、会话恢复、MCP 和 skill 支持。
- Task — 了解排队、停止和重试。