Coze Studio：字节扣子开源版智能体开发平台安装与使用指南

官方信息

项目背景

字节跳动旗下的"扣子"（Coze）是国内最火的低代码 AI 智能体搭建平台之一，很多人用它做客服机器人、知识库问答、自动化工作流。但官方版是 SaaS，数据要上传到字节服务器，企业和隐私敏感团队总觉得不踏实。

2025 年 7 月，字节正式把 Coze 的核心 Studio 端开源（coze-dev/coze-studio），后端用 Go、前端用 TypeScript，提供了可视化的工作流编排、插件系统、知识库（RAG）、多模型接入、记忆系统等完整能力。开源版可以完全私有化部署，接自己的火山方舟、DeepSeek、OpenAI、Ollama 模型，数据不出内网。

项目上线一周 Star 破万，是 2025 年最受关注的国产 AI infra 开源项目之一。它内置了 MySQL、Redis、Milvus 向量库、Elasticsearch、MinIO、NSQ 消息队列等全套中间件，一条 docker compose 就能拉起。

核心特性

• 可视化工作流编排：拖拽节点把模型、插件、代码、知识库串成流程，零代码搭建复杂 Agent。
• 插件生态：内置网页搜索、代码执行、图像理解等插件，支持自定义插件。
• 知识库 RAG：上传 PDF/Word/网页，自动切分、向量化、Milvus 检索。
• 多模型接入：火山方舟 Doubao、OpenAI、Claude、Ollama、Qwen 等 OpenAI 兼容接口都能接。
• 多 Agent 协作：支持多智能体模式，Agent 之间可互相调用。
• 卡片与回复：支持富文本卡片、表单、按钮等交互组件。
• 完整后端栈：MySQL + Redis + Milvus + ES + MinIO + NSQ，生产可用。
• 开源 Apache-2.0：可商用、可二开。

环境要求

• CPU：至少 2 核（推荐 4 核）。
• 内存：至少 4 GiB（推荐 8 GiB，Milvus 比较吃内存）。
• 磁盘：20 GB 以上（镜像 + 向量库）。
• 已安装 Docker 与 Docker Compose v2。
• Linux 推荐 Ubuntu 22.04/24.04；macOS 用 Docker Desktop；Windows 推荐 WSL2。

详细部署步骤

第一步：拉取源码

git clone https://github.com/coze-dev/coze-studio.git
cd coze-studio

第二步：配置模型（首次必做）

Coze Studio 本身不带模型，必须先配置至少一个大模型才能用。从模板复制配置文件：

# 如果用火山方舟 Doubao 模型：
cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml \
   backend/conf/model/ark_doubao-seed-1.6.yaml

# 如果用本地 Ollama 的 Qwen：
cp backend/conf/model/template/model_template_qwen.yaml \
   backend/conf/model/model_qwen.yaml

编辑配置文件，关键三个字段：

# backend/conf/model/ark_doubao-seed-1.6.yaml
id: 1                          # 模型唯一整数 ID，上线后不要改
meta:
  conn_config:
    base_url: "https://ark.cn-beijing.volces.com/api/v3/"
    api_key: "你的火山方舟API Key"
    model: "你的Endpoint ID，如 ep-2025xxxx"

如果接 Ollama 本地模型，base_url 填 http://host.docker.internal:11434/v1，model 填 ollama list 里看到的精确模型名。

第三步：配置 .env

cd docker
cp .env.example .env
# 如需配置 Embedding 模型做知识库 RAG，编辑 .env：
# ARK_EMBEDDING_BASE_URL=https://ark.cn-beijing.volces.com/api/v3/
# ARK_EMBEDDING_MODEL=你的embedding模型ID
# ARK_EMBEDDING_API_KEY=你的key
# ARK_EMBEDDING_DIMS=2048

第四步：启动全部服务

docker compose --profile '*' up -d

首次启动会拉取 MySQL、Redis、Milvus、ES、MinIO、NSQ、etcd 等十多个镜像，预计 5-10 分钟。看到以下状态即成功：

docker compose ps
# coze-mysql         healthy
# coze-redis         healthy
# coze-milvus        healthy
# coze-elasticsearch healthy
# coze-minio         healthy
# coze-server        Up

第五步：访问与注册

浏览器打开 http://服务器IP:8888，首次需要注册一个邮箱+密码账号（没有默认账号）。登录后即可进入工作空间。

常见坑

• Milvus 启动超时：内存不够，至少给机器 4G 以上，或关掉其他吃内存的服务。
• Windows 直接跑 Docker Desktop 报错：官方脚本是 bash 写的，Windows 请用 WSL2。
• agent 调用模型报错：检查 yaml 里的 model 字段是不是和方舟控制台的 Endpoint ID 完全一致；api_key 是否复制完整。
• 镜像拉不下来：国内服务器配置 Docker 镜像加速器。

使用方法示例

登录后：

1. 点左上角"+" → 创建智能体，选刚配置的模型。
2. 在"人设与回复逻辑"里写 Prompt。
3. 中间"技能"区可添加工作流、插件、知识库。
4. 右侧调试面板输入问题测试。
5. 满意后点"发布"，可发布为 API、Web SDK 或企业微信/飞书等渠道。

常见问题（FAQ）

Q1：开源版和官方扣子有什么区别？
A：开源版包含核心的 Agent/工作流/知识库能力，但官方版的商店、商业化发布渠道、豆包深度集成等 SaaS 特性不在开源范围内。

Q2：能接 DeepSeek 吗？
A：可以，用 OpenAI 兼容模板，base_url 填 https://api.deepseek.com/v1，api_key 填 DeepSeek 的 key，model 填 deepseek-chat 或 deepseek-reasoner。

Q3：8888 端口被占用？
A：编辑 docker-compose.yml，把 coze-server 的 8888:8888 改成 9000:8888 之类空闲端口。

Q4：数据存在哪？
A：业务数据在 MySQL，文件在 MinIO，向量在 Milvus，全部通过 docker volumes 持久化在 ./docker/data/ 目录，备份直接打包这个目录即可。

跳转链接

• GitHub 仓库：https://github.com/coze-dev/coze-studio
• 官方文档：https://www.coze.cn/open/docs
• 火山方舟 API Key：https://console.volcengine.com/ark
• 在线版扣子：https://www.coze.cn/