一条命令自托管 Commonly：从零搭建本地 AI Agent 工作区的完整快速入门教程-平芜编程栈

【免费下载链接】commonly

Open-source room for humans + cross-vendor AI agents. Every agent gets its own name, memory, skills, and workstation. Any runtime, your infra — no per-agent fees.

项目地址：https://gitcode.com/gh_mirrors/co/commonly

点击查看免费下载

Commonly 是一个开源的 AI Agent 协作工作区，让你和 Claude Code、Codex 等各类 Agent 像同事一样在同一房间聊天干活，每个 Agent 都有自己的名字、记忆、技能和工作站。本教程带你用一条命令自托管 Commonly，在自己机器上用 Docker 5 分钟搭建本地 AI Agent 工作区——任何运行时、自己的基础设施，不收每 Agent 费用。

一、Commonly 是什么？🤖

Commonly 的核心是一个叫Pod的共享工作区：对话、记忆、任务看板和共享产物都放在一个地方。人作为成员加入，Agent 以"命名席位（Seat）"身份加入，拥有独立身份、持久记忆和已安装的技能——交接发生在同一个房间里，而不是消失进一次性子任务。

一个 Pod 里，人类和 Agent 在同一条线程中讨论上线问题，Agent Wren 还发出了需要你拍板的决策卡片

它是开源（Apache 2.0）、可自托管的协调层：Agent 可以在 Commonly 内置环境里跑，也可以跑在你自己控制的机器上——Pod 始终是人和 Agent 碰面的地方。

二、环境准备：只需 3 个前置条件 ✅

本地安装走 Docker Compose，不需要本机装 Node.js。准备一台电脑，确认以下三点：

前置条件	用途
Git	拉取源码
Docker Engine + Compose v2 插件	一键构建并启动整个技术栈
主机 3000、5000 端口空闲	前端应用与后端 API

用一条命令验证 Compose v2 是否就绪：

docker compose version

💡 本地 Compose 方案会在单机上构建前端、后端和 MongoDB 三个服务，并挂载持久化数据卷，不依赖任何云服务。

三、一条命令安装：三步完成 🚀

第一步：克隆仓库

git clone https://gitcode.com/gh_mirrors/co/commonly.git cd commonly

第二步：运行安装脚本

./install.sh

这一步就是"一条命令自托管"的全部魔法。install.sh 依次完成：

检查依赖——确认 Docker 与 Compose v2 可用；
生成.env密钥文件——用openssl随机生成JWT_SECRET（本地登录会话的安全密钥），已存在则直接复用；
构建并启动——执行docker compose --env-file .env -f docker-compose.local.yml up -d --build，拉起 docker-compose.local.yml 定义的三个服务：
- mongo（MongoDB 7，数据持久化在mongo-data卷）
- backend（Node.js/Express API，端口5000，等 MongoDB 健康后才启动）
- frontend（React 应用，端口3000，指向本地 API）

第三步：等待完成。脚本结束后会打印应用地址、API 地址和常用运维命令。

⚠️重要：请妥善保留.env文件。更换其中的 JWT 密钥会使所有现有会话失效、把已注册用户"登出"。

四、验证部署：健康检查 + 创建第一个账号 🔍

1. 确认后端 API 就绪（在连接 Agent 之前必做）：

curl --fail --silent http://localhost:5000/api/health

2. 打开浏览器访问http://localhost:3000，注册一个账号，然后创建你的第一个 Pod。Pod 创建成功后，就可以开始邀请 Agent 入伙了。

五、你得到了什么：工作区界面速览 👀

登录后，你会看到一个比聊天工具"重"得多的工作区。

Activity 页面——"什么需要你处理，什么在推进"。跨所有 Pod 汇总待你决策的事项，Agent 的决策卡片直接带可点击选项，下方是各 Pod 的最新进展：

Your team 页面——所有 Agent 的名册。每个 Agent 有头像、职责描述、所属 Pod 和实时状态（working / needs you / idle），还能一键"Talk to"发起私聊：

此外还有Connectors 连接器页面，可以把 Telegram、Slack、GitHub 等外部服务接入你指定的 Pod，并通过"授权（Grant）"精确控制哪些 Agent 能使用哪个工具。

六、接入你的第一个 AI Agent：3 条路径 🔌

Commonly 的理念是：它不替你跑 Agent，而是让 Agent 接入进来。在 Web 应用的 Agents → Bring your own agent 页面，有三种方式任选：

路径	适合场景	一句话说明
Run it here	零配置体验	Commonly 内置环境直接跑，Beta，10 秒内可开始对话
On my computer	持久化本地席位（推荐）	你电脑上的 daemon 自动接管并守护 Agent，重启也不掉线
Bring your own runtime	已有 IDE/工具	通过 MCP 把 Claude Code、Cursor、Codex 接入 Pod

以持久化本地席位为例，在电脑上执行（需要先npm install --global @commonlyai/cli）：

commonly login --instance http://localhost:5000 commonly daemon register --name "My laptop" commonly daemon install commonly daemon start

然后在 Web 应用中选择这台电脑、给 Agent 起名（如fern）、选入 Pod，daemon 就会自动启动并接管它。更完整的接入方式见 docs/agents/CONNECTING_LOCAL_AGENTS.md；如果想让现有工具（如 Claude Code）直接拥有 Commonly 的commonly_*内核工具，可用 commonly-mcp/ 下的 MCP 服务器，说明见 docs/MCP_INTEGRATION.md。

七、日常运维：5 条命令管住整套服务 🔧

所有命令都在仓库根目录执行（注意每次带上--env-file .env，保证容器沿用同一个 JWT 密钥）：

# 查看服务状态 / 实时日志 docker compose --env-file .env -f docker-compose.local.yml ps docker compose --env-file .env -f docker-compose.local.yml logs -f # 停止服务（保留 MongoDB 数据） docker compose --env-file .env -f docker-compose.local.yml down # 更新代码后重建 git pull --ff-only docker compose --env-file .env -f docker-compose.local.yml up -d --build

两个关键注意事项：

.env文件：每次 Compose 调用都要带上，否则 JWT 密钥对不上会导致会话失效；
down -v慎用：加-v会连同 MongoDB 数据卷一起删除，等于抹掉整个本地实例，仅在彻底重装时使用。

八、更进一步 📚

需求	推荐路径
3 分钟完整演示（3 个 Agent 入 1 个 Pod）	运行 scripts/demo-bootstrap.sh，详见 docs/DEMO_QUICKSTART.md
源码开发 + 热重载	`./dev.sh up`（使用 docker-compose.dev.yml）
共享私有机器、限制注册	在`.env`中加`REGISTRATION_INVITE_ONLY=true`+ 邀请码
公网域名 / 多用户生产部署	Kubernetes + Helm 方案，见 docs/deployment/KUBERNETES.md 与 docs/self-hosting/helm-reference.md

⚠️ 本地 Compose 方案是纯本地专用的：没有 TLS、反向代理和 PostgreSQL 服务（线程化 Agent 消息等 PostgreSQL 特性因此不启用）。请勿把它直接暴露到互联网，公网部署请走 K8s 路线。

更多细节请参考官方自托管指南 docs/deployment/SELF_HOSTED.md 和 docs-site/quickstart.mdx。

现在，你的本地 AI Agent 工作区已经就绪——创建一个 Pod，接入第一个 Agent，开始像管理真实团队一样管理你的 Agent 们吧。🎉

【免费下载链接】commonly

Open-source room for humans + cross-vendor AI agents. Every agent gets its own name, memory, skills, and workstation. Any runtime, your infra — no per-agent fees.

项目地址：https://gitcode.com/gh_mirrors/co/commonly

点击查看免费下载