Multica 上手指南
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）
brewinstallmultica-ai/tap/multica没有 Homebrew 时：到仓库 github.com/multica-ai/multica 的 README，按其中的 install 脚本说明操作（脚本下载地址以仓库页面为准，此处不展开）。
Windows（PowerShell）
同样以仓库 README 里的 Windows 安装说明为准；装好后在终端执行下面的校验命令即可。
装完看一眼版本：
multica version能打出版本号就说明装上了。之后升级用：
multica update五、一次搞定：登录 + 起 daemon
日常最省事的入口：
multica setup等价于连 Multica Cloud 的：
multica setup cloud它会依次做这些事：
- 把 CLI 指到 Multica Cloud
- 打开浏览器完成登录
- 把个人访问令牌（一般是
mul_前缀）写进本机配置（默认在用户目录下的.multica/config.json） - 自动拉起 daemon：大约每 3 秒轮询任务，每 15 秒心跳一次
自建服务端用：
multica setup self-host（需要自己先有可用的 Multica Server，细节见仓库里的自托管文档。）
分开操作也行
multica login multica daemon startCI / 无头环境可以跳过浏览器，用令牌登录（把下面的占位符换成你自己的令牌）：
multica login--tokenmul_你的令牌令牌在网页设置 → 个人访问令牌里创建。别把令牌写进文档、Issue 评论或截图。
确认 daemon 活着
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 statusmultica daemon logs -f- 确认对应编码工具本身在本机终端能跑通、已登录
多数「Agent 不动」其实是本机问题：daemon 没开、工具没装、Key 过期。
七、创建第一个 Agent
网页路径：设置 → Agents → New Agent。
建议字段：
| 字段 | 怎么填 |
|---|---|
| Name | 看板和评论里显示的名字，好认就行 |
| Provider / Runtime | 选本机已检测到的那个工具 |
| Model | 可选；不填就用 runtime 默认 |
| Instructions | Agent 的「长期行为说明」——职责、边界、输出习惯写这里 |
| Description | 列表里给人看的简介，不会进运行时 prompt |
CLI 最小创建示例（需要先有 runtime id）：
multica runtime list--outputjson multica agent create--namemy-agent --runtime-id<runtime-uuid>\--description"日常改 bug 的助手"\--instructions"先读 Issue 和评论，再改代码；结论用评论回复。"\--outputjson建好之后，它会出现在 workspace 成员列表里，可以像人一样被指派 Issue。
八、派第一个任务
建 Issue
网页上点新建，或 CLI：
multica issue create--title"给 README 加一段安装说明"指派给 Agent
网页点 Agent 头像即可。CLI：
multica issue assign MUL-1--tomy-agent--to支持名字子串匹配；名字容易撞车时用--to-id <uuid>（和--to二选一）。
接下来本机会发生什么
- 大约 3 秒内任务从 queued → dispatched
- daemon 拉起对应编码工具，状态变 running
- Agent 在本机读目录、跑命令、改文件
- 结束后回写 Multica：completed / failed
网页通过 WebSocket 实时刷新，一般不用手动 F5。
九、日常会用到的 CLI
结构化输出建议加--output json，方便脚本或自己排查。
Workspace
multica workspace list multica workspace switch<id或slug>Issue
multica issue list--outputjson multica issue get<id>--outputjson multica issue status<id>in_progress multica issue comment list<id>--recent10--outputjson multica issue commentadd<id>--content-file ./reply.md multica issue runs<id>--outputjson评论里写长文时，Windows 上更稳妥的做法是先把正文存成 UTF-8 文件，再用--content-file，避免管道编码把中文弄丢。
Agent / Runtime
multica agent list--outputjson multica agent get<id>--outputjson multica runtime list--outputjsonProject（给一组 Issue 绑持久上下文）
multica project list--outputjson multica project resource list<project-id>--outputjson项目上可以挂github_repo、local_directory这类资源，后续 Agent 任务 brief 里会带上。
Skill
multica skill list--outputjson multica skillimport<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 用来排障和脚本化。