SELF-HOSTED · 一次真实的自托管落地

把 AI 编程 Agent 当成团队成员来管

Multica 是一个开源平台:你像给同事派活一样,把任务（issue）指派给 AI Agent，它自己调起 Claude Code 去干、汇报进度、改完走 Git 流程。这一页是我在 Mac mini 上从零自托管、亲手把每个机制都验证一遍之后，沉淀下来的实战笔记。

版本 v0.3.15 模式 Self-Hosted 运行时 Claude Code 平台 macOS · Docker

01 / 它是什么

不是替代 Claude Code，是它"上面一层"的指挥台

日常用 Claude Code 是一个人对着一个终端单打独斗。Multica 把这些 Agent 组织成一个有看板的团队：每个 Agent 有头像、会在看板上认领 issue、留评论，甚至自己开 issue。它不写代码本身，而是把 Claude Code 当作可被调度的"工人"，再套一个团队管理的壳。

🧑‍💻

Agent 即同事

给 Agent 设定身份、模型、系统提示，像分配任务给同事一样指派 issue，它自主执行并回报。

🗂️

看板式协作

issue 在待办 → 进行中 → 审核中 → 完成之间自动流转，全程有记录、可追溯。

🔁

可复用与定时

解决过的问题沉淀成可共享的 Skill；Autopilot 可按 cron / webhook 定时触发周期任务。

02 / 我的部署

自托管：数据全在自己机器上

两种模式里我选了 Self-Hosted——前端 / 后端 / 数据库都跑在自己的 Mac 上，数据自己掌控。前提是先装 Docker Desktop，再用官方脚本 install.sh --with-server 一键拉起服务栈。

multica-frontend

Next.js 16 网页面板，localhost:3000，就是你看到的看板界面。

multica-backend

Go 后端（Chi + WebSocket），localhost:8080，管数据、调度、认证。

postgres + pgvector

PostgreSQL 17，存所有数据；pgvector 用于 Skill / 记忆的语义检索。

本地 daemon

真正在你机器上调起 Claude Code 等 CLI 干活的守护进程，重启后需 multica daemon start。

multica CLI

命令行工具，建 agent / issue / 附件全靠它，也是 Agent 自动化的入口。

03 / 核心闭环

派活 → 自动调起 Claude Code → 回报

这是 Multica 的灵魂：你建一个 issue 指派给 Agent，daemon 自动起一个独立的 Claude Code 进程在隔离目录里执行，完成后自动更新状态、把产出写进评论——全程无人值守。

STEP 1

你派 issue

建任务、指派给某个 Agent。

→

STEP 2

daemon 接活

起一个 Claude Code 进程在沙盒里干。

→

STEP 3

自动回报

状态流转 + 产出写进评论。

▸ 实测:demo 任务「计算 1–100 的质数之和」

daemon picked task agent=小助手 provider=claude

claude started pid=75136 · 跑了 7 个工具

claude finished status=completed duration=30.2s

评论产出 → 质数之和 = 1060 ✓ 状态 todo → in_review

04 / 接真实仓库

为什么看的是 GitHub，不是你的本地文件夹

把仓库挂到项目上时，挂的是一个 GitHub 网址。派活时 daemon 按网址做"裸克隆"——从 GitHub 下载一份干净副本到隔离沙盒，Agent 在副本里干活，全程不碰你的本地文件夹。

☁️

可移植

仓库定义成网址，哪天 Agent 换到云端机器跑也成立；指本地路径就只在这台 Mac 有效。

🧊

隔离 / 可复现

每次从 GitHub 拉干净副本，多任务并行不打架，起点稳定。

🔒

避开同步盘

本地是坚果云同步盘，随时被改写；Git 的已提交历史才是可靠基准。

由此引出"策略 A"：Git 不擅长存大二进制（PDF / 图片每改一次就整存一份、看不了 diff）。所以我让 .gitignore 忽略所有图片 / PDF / 音视频——它们继续靠坚果云同步，Git 只承载文字。要让 Agent 处理某个二进制时，用"附件投喂"（见下一节）。

05 / 三种附件投喂

把 PDF / 图片喂给 Agent 的三种方式

不挂仓库、按需把文件直接发给 Agent，是处理 PDF / 图片最干净的办法。实测下来有三种形态，网页是否显示各不同——这是踩了好几次才摸清的。

方式	怎么传	网页是否显示	Agent 能读
A 新建 issue 上传	对话框描述区	✅ 描述里显示可点链接	✅
B 评论框上传	底部 📎 / CLI comment add	✅ 评论下文件块＋下载	✅
C CLI 建 issue 附件	issue create --attachment	❌ 不渲染（仅 CLI/URL 取）	✅

✓

判断上传成功的诀窍：提交前，描述 / 评论里应立刻出现文件名链接或文件块；没出现就是没传上，别提交。（我曾以为传了，其实只在文字里写了文件名，文件根本没落库。）

内联预览（👁）在自托管下是坏的：点预览报"localhost 拒绝连接"。改点 下载（⬇），PDF 正常渲染。

06 / 两层机制 · 安全

"仓库走 GitHub" 与 "Agent 能读本地" 不矛盾

一个容易混的点：既然 Agent 能直接读本地文件，为什么仓库还要绕 GitHub？因为这是两个不同层次。

对比	① repo 功能（走 GitHub）	② Agent 本体能力（读本地）
是什么	Multica 的一个功能：给项目挂仓库	Agent 本质是本机一个全权 Claude Code
怎么拿文件	刻意从 GitHub 克隆干净副本到沙盒	有 Bash / Read，能 cat 你账户能访问的任意路径
看得到本地未 push 改动？	❌ 看不到（读的是 GitHub 克隆）	✅ 直接读硬盘实时文件

⚠

安全含义（务必知道）：每个任务都以 --permission-mode bypassPermissions 启动，即全权、无弹窗——Agent 实际能读、甚至改你 Mac 上你账户能碰的任何文件。单机自用没问题，但切勿在共享 workspace 接入不信任的人 / 任务（别人派的 issue 在你机器上也是全权执行）。

07 / 运维备忘

常用命令与关键路径

启停服务栈

cd ~/.multica/server && docker compose -f docker-compose.selfhost.yml up -d / down

daemon

multica daemon start / stop / status（Mac 重启后需手动 start）

取登录验证码

没配 SMTP，验证码打印在日志：docker logs --tail 20 multica-backend-1 | grep "Verification code"

关键路径

服务端 ~/.multica/server/ · 配置 ~/.multica/config.json · CLI ~/.local/bin/multica

08 / 踩过的坑

装 / 用过程中真实踩过的坑

安装 CLI 卡死：官方脚本默认往 /usr/local/bin 装、要 sudo，无终端输密码就僵住。解法：装到无需 sudo 的 ~/.local/bin（或在能输密码的终端里跑）。

登录验证码收不到：自托管没配邮件服务，邮件发不出去。验证码其实打印在后端日志里，去日志捞。

固定验证码不生效：MULTICA_DEV_VERIFICATION_CODE 这个版本没用，还是得翻日志取真实随机码；且 OAuth 回调有超时，登录要快。

GitHub 仓库滞后本地：本地领先远程 13 个 commit 没 push，Agent 只看到旧快照。要让它看最新内容，得先 git push。

附件"看不到"乌龙：多数时候是压根没传成功（只在文字里写了文件名）；CLI 挂的 issue 级附件 UI 也不渲染。规律见第 05 节。