守护进程与运行时
了解 Multica 如何连接电脑、发现 AI 编程工具并运行。
Multica 负责记录和协调工作，连接的电脑负责执行。电脑上的守护进程（daemon）领取运行，再调用本机安装的 AI 编程工具。
Qoder Cloud Agent 远端运行时
Qoder Cloud Agent 通过远端会话执行分配的任务。Multica 服务端管理桥接进程，复用现有守护进程任务协议，无需用户启动本地守护进程。
准备工作
- 需要工作区管理员权限。每个工作区只有一个 Qoder 连接。
- 在 Qoder 中创建个人访问令牌（PAT）、至少一个运行环境，以及要使用的 QCA 智能体。模型、工具和 skill 都在 Qoder 的 QCA 智能体上配置，不在 Multica 中配置。
- 自托管部署需在服务端设置
MULTICA_VCS_SECRET_KEY：一个 base64 编码的 32 字节密钥，重启前后必须保持不变。未设置时，添加菜单中不会出现 Qoder Cloud Agent。
连接 Qoder
- 在运行时页面点击添加，在云服务下选择 Qoder Cloud Agent。
- 在服务区域中选择签发 PAT 的站点：国际站（qoder.com）或中国站（qoder.com.cn）。PAT 只在签发它的站点有效；如果被拒绝，可点击按钮改用另一站点重试。
- 将 PAT 粘贴到个人访问令牌。验证通过后会从 Qoder 加载运行环境列表；只有一个环境时自动选中，否则手动选择。
- 可选：展开 GitHub 仓库授权，为智能体需要克隆的每个仓库填写仓库 URL 和令牌。智能体只能克隆这里授权过的仓库。
- 可选：展开执行设置，设置并发运行数（默认 3，最多 10）和运行超时（默认 60 分钟，可设 5 到 240 分钟）。
- 点击连接。Qoder Cloud Agent 会出现在运行时页面的云服务分组中，几秒内上线。
添加智能体
在运行时页面打开 Qoder Cloud Agent，点击用它创建智能体；也可以照常创建智能体并选择 Qoder 运行时。在智能体表单的 QCA 智能体中选择远端智能体。已有智能体可在路由标签页中修改关联的 QCA 智能体或默认仓库。多个 Multica 智能体可以共用同一个连接，各自关联不同的 QCA 智能体。
连接凭证加密保存，在工作区内共享。管理员管理连接，成员可以选择可访问的 QCA 智能体。项目选择仓库和起始分支；创建编码会话时，对应仓库的令牌会传给 QCA。保存后的 PAT 不会返回浏览器。
管理员可以在 Qoder Cloud Agent 页面编辑连接和仓库；点击暂停停止下发新任务，凭证和智能体保留；点击断开连接删除已保存的令牌、移除该运行时并解绑其智能体。
运行方式
超出并发上限的任务会排队等待。同一任务的后续运行会在上一会话空闲时继续使用该 Qoder 会话。智能体可以设置默认仓库，在任务所属项目未绑定仓库时使用。智能体会被要求以任务标识命名分支，并在 PR 标题前加上任务标识，以便 PR 自动关联到任务。
首版支持任务运行、进度同步、取消和基于持久化记录的恢复。模型、工具和 skill 在 Qoder 中配置；暂不支持交互聊天、本地目录、附件，也不支持从 Multica 创建远端 QCA 智能体。运行时页面分别展示远端运行时和电脑。
独立桥接进程的配置与限制见 Qoder runtime README。
概念区分
- 守护进程是运行在一台电脑上的 Multica 后台程序。它负责连接服务器、发现本机工具、领取运行和回传结果。
- 运行时代表一个工作区可以使用的具体执行环境。它对应一台电脑，以及这台电脑上的一款 AI 编程工具或自定义运行时配置。
例如，一台电脑同时安装了 Claude Code 和 Codex，并连接两个工作区。守护进程会分别为两个工作区注册 Claude Code 和 Codex 运行时。重启守护进程会更新原有记录，不会为同一个组合不断创建新运行时。
执行位置与数据边界
本地运行时调用的 AI 编程工具、这些工具自己的登录凭据，以及本地代码目录都留在连接的电脑上。Multica 服务器不会代替本地工具执行命令，也不会自动上传整个工作目录。
为了让团队能够协作，服务器会保存任务、评论、智能体配置、运行上下文、执行记录和智能体写回的结果。这些内容可能包含智能体主动读取并写入回复的代码片段或其他项目上下文。
智能体的自定义环境变量保存在服务器侧，并在执行时发送给运行时。不要把"本地执行"理解为所有 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 | 在当前终端中运行，便于调试 |
如需把执行工作目录放到其他磁盘，可用 multica config set workspaces_root <path> 为当前 profile 持久化根目录，也可在 daemon start 或 daemon restart 中传入 --workspaces-root <path>。flag 的优先级高于 MULTICA_WORKSPACES_ROOT，环境变量又高于 profile 配置。修改根目录不会迁移已有的执行目录。
启动时，守护进程会检测 PATH 中受支持的 AI 编程工具，并为你有权连接的工作区注册运行时。如果一款工具刚刚安装或登录，重启守护进程即可重新检测。
守护进程至少需要检测到一款内置支持的 AI 编程工具才能启动。安装方法和可执行文件名见安装 AI 编程工具。
派发与在线状态
运行时注册后会持续保持连接。新运行入队时，服务器会通知对应守护进程；守护进程也会定期轮询，作为连接中断后的补充。因此运行时在线且有空闲容量时，运行通常会立即开始。
守护进程每 15 秒发送一次心跳。服务端综合心跳与连接状态判断运行时是否在线；守护进程意外退出后，最迟通常会在约 3 分钟内显示为离线。
运行时离线时：
- 已经排队的运行会等待运行时恢复，只有当它心跳缺席超过重连宽限期且该运行自己也已排队满这么久时才会失败；所以运行时只是忙的话积压会一直保留，指派给已离线运行时的工作也仍然有完整一个宽限期可以等待。
- 正在执行的运行会失败；符合条件的任务或对话运行可以自动重试。
- 守护进程重新启动后，会重新注册运行时，并回收上一次没有正常结束的运行。
- 离线超过 7 天且没有任何智能体（包括已归档的）绑定的运行时，会被自动清理。
详细状态和重试规则见运行。
并发限制
一台守护进程默认最多同时执行 20 次运行；每个智能体默认最多同时执行 6 次。实际并发取两者中的较小值。
达到上限后，新运行会继续排队。你可以在智能体设置中调整单个智能体的并发数，也可以通过 MULTICA_DAEMON_MAX_CONCURRENT_TASKS 调整整台电脑的上限。并行执行会同时占用机器性能、工具账号额度和同一工作目录。
私有与公开
本地运行时默认是私有的：只有运行时所有者可以在它上面创建智能体。工作区的 owner、admin 也不例外——运行时是别人的电脑，在上面跑智能体消耗的是对方的机器和工具凭据。
只有运行时所有者可以把它改为公开——管理员可以重命名或删除运行时，但要不要共享由所有者决定。公开后，工作区中的其他成员也可以选择这条运行时；这不会分享底层 AI 编程工具的登录凭据，只是允许成员把智能体的执行路由到这台电脑。
所有者把公开运行时重新设为私有时，Multica 会先展示受影响的智能体和活动运行，包括智能体构建会话。确认后会解绑其他成员的这些智能体，以 runtime_access_revoked 取消其排队中、已调度、执行中、等待本地目录和延迟中的运行，并暂停分配给这些智能体的已启用自动化。所有者自己的智能体和运行不受影响。影响范围变化时需要重新确认；遇到并发聊天写入时可能需要重试。恢复工作时，请先将智能体绑定到可用的运行时，再手动恢复已暂停的自动化。
取消会保留聊天历史，并在服务端保存草稿和附件恢复数据。网页端和桌面端沿用现有的草稿恢复入口；移动端暂未提供该入口。已开始但尚无输出的运行，会等待守护进程确认取消或服务端收尾宽限期结束，再决定是否恢复输入。已连接的守护进程通过常规检查接收取消。电脑离线时，服务端仍会立即撤销访问，但本地进程可能继续执行，直到重新连接并收到取消；服务端无法保证立即远程停止。
自定义运行时配置
如果团队使用内部 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 提供，但在 Windows 上 task 会继承用户临时路径以维持 Git Bash 的共享 /tmp；Windows 上的 Claude Code 会将 CLAUDE_CODE_TMPDIR 默认设为 task 临时目录 | 仅供参考 |
使用 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，升级后请发起一次运行，确认它仍能正常启动。
另有两点需要注意：
- 冲突时以 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>修改配置只影响之后领取的运行。删除配置前，需要先处理仍绑定在对应运行时上的活动智能体。只删除某台电脑上的运行时实例并不会删除配置，运行中的守护进程还会重新注册它。
运行时离线的排查
按以下顺序检查：
- 运行
multica daemon status，确认守护进程已经启动。 - 运行
multica daemon logs -f，查看登录、网络或工具检测错误。 - 在同一运行环境中执行
command -v <工具命令>，确认守护进程能够找到它。 - 打开 Multica 的运行时页面，检查目标电脑和对应的 AI 编程工具是否显示在线。
- 工具刚安装、路径刚修改或配置刚更新时，运行
multica daemon restart。
仍未解决时，参见故障排查。
接下来
- 安装 AI 编程工具 — 安装并验证一款受支持的 AI 编程工具。
- AI 编程工具对照 — 比较模型、会话恢复、MCP 和 skill 支持。
- 运行 — 了解排队、停止和重试。