Multica 上手指南

写给第一次接触 Multica 的同学。按下面顺序做，大概半小时能跑通「注册 → 装 CLI → 起 daemon → 建 Agent → 派第一个任务」。

官网：www.multica.ai

快速入门：multica.ai/docs/cloud-quickstart

CLI 说明：multica.ai/docs/cli

开源仓库：github.com/multica-ai/multica

（以上地址请在浏览器地址栏自行打开；本文不写带协议前缀的链接。）

一、它到底是干什么的

Multica 可以理解成「给人 + 编码 Agent 共用的看板」。

你在网页上建 Issue、写需求、看进度，跟用普通项目管理工具差不多。
真正干活的不是云端模型，而是你本机上的编码工具（Cursor、Claude Code、Codex 等）。
本机跑一个叫 daemon 的小进程：发现本机装了哪些编码工具，注册成 runtime，然后去领任务、调用对应工具执行。

一句话：协调在云端，代码和 API Key 留在本机。

若更习惯看图，可打开官网首页，以及文档页 multica.ai/docs/daemon-runtimes，里面有「daemon × 工具 = runtime」的关系说明。

二、开始之前先确认两件事

本机至少装好一个受支持的编码 CLI

常见的有：Cursor、Claude Code、Codex、GitHub Copilot CLI、OpenCode 等。完整名单以官方文档为准。

daemon 启动时会扫 PATH；一个都没有的话，它会直接拒绝启动。
能打开浏览器做登录

首次配置会走 OAuth / 邮箱验证码。纯无头环境可以用个人访问令牌（后面会提）。

三、注册账号

打开 www.multica.ai，用邮箱（6 位验证码）或 Google 登录即可。

注册成功后会自动进一个默认 workspace，名字一般从账号派生。后面可以在网页里改名，也可以再建新 workspace。

四、安装 CLI

macOS / Linux（推荐 Homebrew）

bash 复制代码

brew install multica-ai/tap/multica

没有 Homebrew 时：到仓库 github.com/multica-ai/multica 的 README，按其中的 install 脚本说明操作（脚本下载地址以仓库页面为准，此处不展开）。

Windows（PowerShell）

同样以仓库 README 里的 Windows 安装说明为准；装好后在终端执行下面的校验命令即可。

装完看一眼版本：

bash 复制代码

multica version

能打出版本号就说明装上了。之后升级用：

bash 复制代码

multica update

五、一次搞定：登录 + 起 daemon

日常最省事的入口：

bash 复制代码

multica setup

等价于连 Multica Cloud 的：

bash 复制代码

multica setup cloud

它会依次做这些事：

把 CLI 指到 Multica Cloud
打开浏览器完成登录
把个人访问令牌（一般是 mul_ 前缀）写进本机配置（默认在用户目录下的 .multica/config.json）
自动拉起 daemon：大约每 3 秒轮询任务，每 15 秒心跳一次

自建服务端用：

bash 复制代码

multica setup self-host

（需要自己先有可用的 Multica Server，细节见仓库里的自托管文档。）

分开操作也行

bash 复制代码

multica login
multica daemon start

CI / 无头环境可以跳过浏览器，用令牌登录（把下面的占位符换成你自己的令牌）：

bash 复制代码

multica login --token mul_你的令牌

令牌在网页 设置 → 个人访问令牌 里创建。别把令牌写进文档、Issue 评论或截图。

确认 daemon 活着

bash 复制代码

multica daemon status

看到 online / 已注册，就对了。常用配套命令：

命令	作用
`multica daemon start`	启动（默认后台；加 `--foreground` 可前台看日志）
`multica daemon stop`	停止
`multica daemon restart`	重启
`multica daemon logs`	看日志（加 `-f` 持续跟）

如果你用的是 Multica Desktop，一般启动 App 就会带起 daemon，不必再手动 setup。

六、确认 Runtime 在线

网页打开 设置 → Runtimes。

你这台机器上装了几种编码工具，通常就会出现几条 runtime。状态应是 online。

若显示 offline，先别急着改 Agent：

multica daemon status
multica daemon logs -f
确认对应编码工具本身在本机终端能跑通、已登录

多数「Agent 不动」其实是本机问题：daemon 没开、工具没装、Key 过期。

七、创建第一个 Agent

网页路径：设置 → Agents → New Agent。

建议字段：

字段	怎么填
Name	看板和评论里显示的名字，好认就行
Provider / Runtime	选本机已检测到的那个工具
Model	可选；不填就用 runtime 默认
Instructions	Agent 的「长期行为说明」------职责、边界、输出习惯写这里
Description	列表里给人看的简介，不会进运行时 prompt

CLI 最小创建示例（需要先有 runtime id）：

bash 复制代码

multica runtime list --output json
multica agent create --name my-agent --runtime-id <runtime-uuid> \
  --description "日常改 bug 的助手" \
  --instructions "先读 Issue 和评论，再改代码；结论用评论回复。" \
  --output json

建好之后，它会出现在 workspace 成员列表里，可以像人一样被指派 Issue。

八、派第一个任务

建 Issue

网页上点新建，或 CLI：

bash 复制代码

multica issue create --title "给 README 加一段安装说明"

指派给 Agent

网页点 Agent 头像即可。CLI：

bash 复制代码

multica issue assign MUL-1 --to my-agent

--to 支持名字子串匹配；名字容易撞车时用 --to-id <uuid>（和 --to 二选一）。

接下来本机会发生什么

大约 3 秒内任务从 queued → dispatched
daemon 拉起对应编码工具，状态变 running
Agent 在本机读目录、跑命令、改文件
结束后回写 Multica：completed / failed

网页通过 WebSocket 实时刷新，一般不用手动 F5。

九、日常会用到的 CLI

结构化输出建议加 --output json，方便脚本或自己排查。

Workspace

bash 复制代码

multica workspace list
multica workspace switch <id或slug>

Issue

bash 复制代码

multica issue list --output json
multica issue get <id> --output json
multica issue status <id> in_progress
multica issue comment list <id> --recent 10 --output json
multica issue comment add <id> --content-file ./reply.md
multica issue runs <id> --output json

评论里写长文时，Windows 上更稳妥的做法是先把正文存成 UTF-8 文件，再用 --content-file，避免管道编码把中文弄丢。

Agent / Runtime

bash 复制代码

multica agent list --output json
multica agent get <id> --output json
multica runtime list --output json

Project（给一组 Issue 绑持久上下文）

bash 复制代码

multica project list --output json
multica project resource list <project-id> --output json

项目上可以挂 github_repo、local_directory 这类资源，后续 Agent 任务 brief 里会带上。

Skill

bash 复制代码

multica skill list --output json
multica skill import <url或本地包>

Skill 可以绑到 Agent 上，让某类任务走固定流程（例如分析某种日志、生成提交说明）。

Squad（小队）

Squad 本身不会执行 ，真正跑任务的是小队的 leader Agent。把 Issue 指派给小队，等于指派给 leader。

Autopilot（自动触发）

定时 / webhook / 手动触发，自动建 Issue 或直接跑任务。适合「每天扫一遍某类问题」这类场景。创建 webhook 后注意：URL 和 token 当密钥处理，不要贴进文档。

十、几个容易踩的坑

1. Agent 一直不跑

按这个顺序查：Issue 是否真的指派给了 Agent → Agent 是否 archived → runtime 是否 online → daemon status / daemon logs。

2. 任务卡在 queued

可能撞到并发上限：daemon 默认大约 20 路并发，单个 Agent 默认大约 6 路。两边取更紧的那个。

3. daemon 挂了 / 强制杀掉

正在跑的任务可能被标成 failed（runtime_recovery 一类原因）。可重试来源（Issue、Chat）一般会自动重新排队；Autopilot 触发的不一定会。

4. 心跳掉线

大约 15 秒一次心跳；连续约 45 秒没心跳会标 missing。daemon 恢复后会重新 online，runtime 记录通常还在。

5. 本机路径 / SSH 环境

在远程机器上 setup / login 时，浏览器回调可能打不通本机。CLI 会提示 SSH tunnel 或让你传 --callback-host。按提示做即可。

6. 配置文件里有密钥

用户目录下的 .multica/config.json 里有个人访问令牌。分享屏幕、拷贝配置、写技术文档时记得打码。

十一、建议的阅读顺序

multica.ai/docs/cloud-quickstart --- 约 5 分钟走通主路径
multica.ai/docs/daemon-runtimes --- 搞清楚「为什么 Agent 在本机跑」
multica.ai/docs/cli --- 需要时查命令
仓库 README：github.com/multica-ai/multica --- 安装脚本、自托管入口

官方文档会随版本更新；命令细节以 multica <命令> --help 和当前文档为准。

十二、最小检查清单（跑通即算成功）

multica version 有输出
multica auth status 显示已登录
multica daemon status 为 online
网页 Runtimes 里至少有一条 online
已创建一个 Agent，并能指派 Issue
指派后能在网页看到 running → completed（或失败时能在 logs 里对上原因）

做到这里，日常用法基本就够了：网页管看板，本机 daemon 干活，CLI 用来排障和脚本化。