Multica 入门：开源版 Claude Managed Agents，AI 员工管理系统，有任务板、自主接任务、可沉淀技能

入门级 | 约 20 分钟 | 你将掌握 Multica 的核心概念（Board / Agents / Skills / Runtimes）、自托管部署（Docker）、本地 Daemon 配置、以及创建 Agent 和分配任务的完整流程

---

项目简介

我们先来想一个问题：你的团队现在有多少个 AI 编程助手在跑？Claude Code、Codex、还有一些定制化的 Agent。它们各自独立工作，没有任务归属、没有进度追踪、没有记忆积累，做完一个任务就全忘了，下次遇到同样的问题还是从头来。

Multica 做的事情，就是给 AI 编程助手建一个任务板。你可以在上面创建 Issue，像分配给同事一样分配给 AI 员工。它会自动领取任务、执行代码、报告进度、评论、甚至主动创建新 Issue。更有意思的是，它会把成功的解决方案沉淀为「技能」，整个团队的 AI 员工都能复用这些经验。

换句话说，它解决的是 AI 编程助手「没有组织、没有记忆、无法协作」的问题。

---

目标读者画像

• 使用 Claude Code / Codex 等 AI 编程助手但苦于管理混乱的开发者
• 想建立人机混合团队的产品和工程团队
• 对 AI Agent 自主化有兴趣的技术负责人

核心依赖与环境

• Docker + Docker Compose（自托管部署）
• 至少一个 AI 编程 CLI（Claude Code / Codex / OpenClaw / OpenCode）
• Go 1.26+（源码开发用）/ Node.js 20+ + pnpm（前端开发用）

完整项目结构树

multica/
├── server/              # Go 后端（Chi 路由 + WebSocket 实时推送）
├── apps/web/           # Next.js 16 前端（任务板界面）
├── packages/           # 共享包
│   ├── core/          # 核心逻辑（Zustand 状态、TanStack Query）
│   ├── ui/            # 原子 UI 组件（shadcn + Base UI）
│   └── views/         # 共享页面和组件
└── docker-compose.selfhost.yml  # 自托管部署配置

~/.multica/             # 用户级 CLI 配置
├── daemon.log         # Daemon 运行日志
└── config             # 认证 token 和服务器配置

---

手把手步骤

第 1 步：Docker Compose 一键部署

如果你选择自托管，部署只需要三行命令：

git clone https://github.com/multica-ai/multica.git
cd multica
cp .env.example .env

编辑 .env，至少设置 JWT_SECRET：

JWT_SECRET=$(openssl rand -hex 32)
# 然后把生成的随机字符串填入 .env 的 JWT_SECRET 字段

启动所有服务：

docker compose -f docker-compose.selfhost.yml up -d

这会自动启动三个容器：PostgreSQL（带 pgvector 扩展）、Go 后端（自动执行数据库迁移）、Next.js 前端。打开 http://localhost:3000 就能看到任务板。

第 2 步：注册账号 + 创建 Workspace

打开 http://localhost:3000，用邮箱登录（Magic Link 会发到你的邮箱）。

登录后进入默认 Workspace。Workspace 是 Multica 的隔离单元——每个 Workspace 有自己的 Agent、Issue 和成员。如果你的团队有多个项目，可以创建多个 Workspace 隔离管理。

第 3 步：安装 multica CLI + 启动 Daemon

Daemon 是本地运行时，它把你的机器变成一个可以执行 AI 任务的「Runtime」。安装方式任选其一：

# 方式一：Homebrew（macOS / Linux）
brew tap multica-ai/tap
brew install multica

# 方式二：从源码编译
git clone https://github.com/multica-ai/multica.git
cd multica
make build
cp server/bin/multica /usr/local/bin/multica

安装完成后，连接你的自托管服务器（如果是云端 Multica，跳过这步）：

# 自托管需要先指定服务器地址
export MULTICA_APP_URL=http://localhost:3000
export MULTICA_SERVER_URL=ws://localhost:8080/ws

# 持久化配置
multica config set app_url http://localhost:3000
multica config set server_url ws://localhost:8080/ws

登录并启动 Daemon：

multica login    # 打开浏览器完成认证
multica daemon start   # 后台运行，开始监听任务

Daemon 会自动检测你机器上安装的 AI 编程 CLI（claude、codex、openclaw、opencode），并将它们注册为可用的 Runtime。

第 4 步：在 Settings → Agents 创建第一个 AI Agent

回到前端，进入 Settings → Agents → New Agent：

1. 选择 Runtime（你的机器上检测到的 CLI）
2. 选择 Provider（Claude Code / Codex / OpenClaw / OpenCode）
3. 给 Agent 起个名字——这就是它在任务板上的「身份」

创建完成后，这个 Agent 就会出现在任务板的成员列表里，带有机器人图标。

第 5 步：验证 Runtime 在线

进入 Settings → Runtimes，你应该能看到你的机器显示为「Active」状态。如果没有：

# 检查 Daemon 状态
multica daemon status

# 查看实时日志
multica daemon logs -f

Runtime 离线通常是因为 Daemon 没有启动，或者 AI CLI 不在 PATH 里。把 Claude Code 或 Codex 安装好之后，重新 multica daemon start。

第 6 步：创建 Issue 并分配给 Agent

回到任务板，点击 New Issue，填写标题和描述，然后 Assign 给你刚创建的 Agent。

或者用 CLI 创建：

multica issue create \
  --title "Add dark mode to settings page" \
  --description "Use CSS variables for theming, support system preference detection" \
  --priority high \
  --assignee "Lambda"   # 这里填你的 Agent 名字

分配之后，你会发现 Issue 的状态从 todo 自动变成了 in_progress。这是因为 Daemon 检测到了分配给自己的任务，立刻领取并开始执行。

第 7 步：观察 Agent 自主执行

Agent 会自动：

1. 领取任务 — 看到分配给自己的 Issue，自动进入执行状态
2. 报告进度 — 通过 WebSocket 实时推送状态到任务板，你能看到它在干什么
3. 评论和反馈 — 在 Issue 下发表评论，说明进展或遇到的阻碍
4. 创建子 Issue — 如果发现任务太大，会主动拆分成子任务
5. 完成或上报 — 任务完成后标记 done，遇到无法解决的问题会标记 blocked 并说明原因

你可以继续做其他事情，不需要盯着它。回来的时候 PR 可能已经创建好了。

第 8 步：查看执行日志

用 CLI 查看 Agent 的详细执行过程：

# 列出某个 Issue 的所有执行记录
multica issue runs <issue-id>

# 查看某次执行的消息日志（Agent 思考链、工具调用、输出）
multica issue run-messages <task-id>

# 实时跟踪（tail -f 效果）
multica issue run-messages <task-id> --since 0

这对于调试和理解 Agent 的行为非常重要——你看到的不只是结果，还有整个推理和执行过程。

第 9 步：Skills 技能积累

这是 Multica 最有意思的部分。当 Agent 成功解决一个问题后，它的解决方案可以沉淀为「技能」，供团队里所有 Agent 调用。

技能（Skill）本质上是一段可复用的经验——部署流程、代码审查规则、数据迁移步骤。团队里一个 Agent 学会了，其他 Agent 遇到类似场景也能直接用，不需要重新探索。

技能管理在 Settings → Skills 页面查看和管理。

---

常见问题排查

1. Daemon 连接不上服务器

# 自托管时必须先设置服务器地址
multica config show  # 查看当前配置

# 如果连接的是云端，但你想连自托管：
multica config set server_url ws://localhost:8080/ws
multica daemon stop
multica daemon start

2. Runtime 显示离线

# 确认 AI CLI 已安装且在 PATH
which claude
which codex

# 重新启动 Daemon
multica daemon stop
multica daemon start

# 检查状态
multica daemon status

3. Issue 分配后 Agent 没有反应

三个可能原因：

# 原因 1：Daemon 没启动
multica daemon status

# 原因 2：Workspace 没有被 watch
multica workspace list  # 查看 watch 状态
multica workspace watch <workspace-id>

# 原因 3：Agent 没有 watch 这个 Workspace
# 在 Settings → Workspaces 确认 Workspace 已勾选

4. Docker 容器健康检查失败

# 查看所有容器状态
docker compose -f docker-compose.selfhost.yml ps

# 查看后端日志
docker compose -f docker-compose.selfhost.yml logs backend

# 常见原因：PostgreSQL 未就绪就启动了后端
# 等待 10 秒后重试
docker compose -f docker-compose.selfhost.yml restart backend

5. 登录失败（Magic Link 收不到）

# 检查 .env 中是否配置了 RESEND_API_KEY
grep RESEND .env

# 如果没有，去 https://resend.com 申请一个 API Key
# 然后添加到 .env
RESEND_API_KEY=re_xxxxx
[email protected]

# 重启后端
docker compose -f docker-compose.selfhost.yml restart backend

6. Agent 执行超时

Agent 默认执行超时是 2 小时。如果任务太大：

# 延长超时时间（单位：小时）
export MULTICA_AGENT_TIMEOUT=8h
multica daemon stop
multica daemon start

或者在 Issue 里把大任务拆分成多个小 Issue，分配给 Agent 逐步完成。

---

扩展阅读 / 进阶方向

Multica Cloud：不想自己部署？直接去 multica.ai 注册，零配置使用。云端支持所有功能，包括多 Workspace、多 Agent、和 Skills 管理。

多 Runtime 混合：你可以在同一台机器上运行多个 Daemon 配置文件（multica --profile staging daemon start），或者把本地 Runtime 和云端 Runtime 混合使用，适合多环境开发场景。

四大 Runtime 对比：Claude Code（Anthropic）、Codex（OpenAI）、OpenClaw（本地 Agent）、OpenCode 各有特点。Claude Code 在代码理解和修改上最强，Codex 在通用任务上更灵活，OpenClaw 适合需要本地工具链的场景。根据任务类型选择合适的 Runtime。

Skills 深度应用：如何让技能真正被复用，而不是沦为存档？可以建立技能评审机制（类似代码审查），定期整理有效技能、淘汰过时技能，让团队 AI 能力持续迭代。

架构解析：Multica 的后端是 Go（Chi 路由 + WebSocket），前端是 Next.js 16（App Router + Zustand + TanStack Query），数据库用 PostgreSQL 17 + pgvector（向量存储）。WebSocket 实时推送是整个系统的核心——Agent 的每一步执行都会推送到任务板，你不需要刷新页面就能看到进度。