【全网最全】Coze Studio 扣子开发平台 Windows /Mac / Linux 本地部署教程，小白也能轻松搞定！

推荐语

字节跳动开源AI开发神器Coze Studio，手把手教你本地部署，轻松打造专属AI应用！

核心内容：
1. Coze Studio开源版功能与优势介绍
2. 详细的环境准备与安装步骤指南
3. 模型配置与项目构建的实用技巧

杨芳贤

53AI创始人/腾讯云(TVP)最具价值专家

本文以完整的教程来教会大家如何获取并部署 Coze Studio 开源版，快速构建项目、体验 Coze Studio 开源版。

字节跳动于2025年7月25日晚间正式开源了扣子的两个核心项目——Coze Studio（扣子开发平台） 和 Coze Loop（扣子罗盘）。

先简要介绍下两个项目：

Coze Studio （扣子开发平台）是扣子（Coze）官方的开源版本，是一个面向开发者的AI Agent 可视化设计与编排工具。

Coze Loop（扣子罗盘） 是一个面向开发者的AI Agent 运维与生命周期管理平台，用于配合 Coze Studio 实现完整的 Agent 管理体验。

这意味着无论是个人开发者还是企业团队，现在都可以在本地或云端部署和使用扣子平台，打造属于自己的 AI Agent 应用。

现在带着大家来完成Coze Studio开源版的安装。

环境要求

在参考本文安装 Coze Studio 之前，确保您的软硬件环境满足以下要求：

安装 Coze Studio

步骤一：获取源码

在本地项目中执行以下命令，获取 Coze Studio 最新版本的源码。

# 克隆代码 
git clone https://github.com/coze-dev/coze-studio.git

备注: git是一个从代码仓库拉取代码的工具，大家通过以下网址下载，安装一下即可，安装非常简单，安装以后，就可以使用git命令了。如果你没有安装git，请先安装git：https://git-scm.com/downloads

当然，如果你不想安装git，你也可以直接下载github的zip包，如下图：

步骤二：配置模型

Coze Studio 是基于大语言模型（LLM）的 AI 应用开发平台，首次部署并启动 Coze Studio 开源版之前，你需要先在 Coze Studio 项目里配置模型服务，否则创建智能体或者工作流时，无法正常选择模型。

本文档以火山方舟模型为例，演示如何为 Coze Studio 配置模型服务。如果你准备使用 OpenAI 等其他在线模型服务，应参考模型配置（https://github.com/coze-dev/coze-studio/wiki/3.-模型配置）文档正确填写配置文件。

1. 1. 从模板目录复制 doubao-seed-1.6 模型的模版文件，并粘贴到配置文件目录。



2. cd coze-studio
   # 复制模型配置模版
   cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml

   
   
3. 2. 在配置文件目录下，修改模版文件。

• • id：Coze Studio 中的模型 ID，由开发者自行定义，必须是非 0 的整数，且全局唯一。模型上线后请勿修改模型 id。
• • meta.conn_config.api_key：在线模型服务的 API Key，在本示例中为火山方舟的 API Key，获取方式可参考获取火山方舟 API Key（https://www.volcengine.com/docs/82379/1541594）。
• • meta.conn_config.model：在线模型服务的 model ID，在本示例中为火山方舟 doubao-seed-1.6 模型接入点的 Endpoint ID，获取方式可参考获取 Endpoint ID（https://www.volcengine.com/docs/82379/1099522）。

1. 1. 进入目录 backend/conf/model。打开文件ark_doubao-seed-1.6.yaml。
2. 2. 设置 id、meta.conn_config.api_key、meta.conn_config.model 字段，并保存文件。

   

• • id：Coze Studio 中的模型 ID，由开发者自行定义，必须是非 0 的整数，且全局唯一。模型上线后请勿修改模型 id。
• • meta.conn_config.api_key：在线模型服务的 API Key，在本示例中为火山方舟的 API Key，获取方式可参考获取火山方舟 API Key（https://www.volcengine.com/docs/82379/1541594）。
• • meta.conn_config.model：在线模型服务的 model ID，在本示例中为火山方舟 doubao-seed-1.6 模型接入点的 Endpoint ID，获取方式可参考获取 Endpoint ID（https://www.volcengine.com/docs/82379/1099522）。

第一个参数ID请自行设置。

第二个参数 API Key：

第三个参数model：

步骤三：部署并启动服务

首次部署并启动 Coze Studio 需要拉取镜像、构建本地镜像，可能耗时较久，请耐心等待。如果看到提示 "Container coze-server Started"，表示 Coze Studio 服务已成功启动。

# 启动服务
cd docker
cp .env.example .env
docker compose --profile '*' up -d

步骤四：登录访问

单Agent自主规划智能体

插件生态

工作流

小通体验感受

与公网扣子开发平台相比：

1、缺少对话流、对话智能体、多Agent，缺少AI应用；

2、缺少自定义空间；

3、发布渠道只支持WEB SDK和API（我觉得这个选择是正确的）；

4、授权体系只支持个人令牌，还只能设置30天；

其他核心的能力该有的也有了，诚意够，但不多。会开发能力的倒是一个相比dify、N8N、FastGPT等更好的选择。

FAQ：本地部署踩坑指南

1、Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:3306 -> 0.0.0.0:0: listen tcp 0.0.0.0:3306: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

这个问题是因为我本地MySQL服务启动着，占用了3306的端口。而coze studio开源默认MySQL对外端口是3306，所以冲突了导致。

修改（coze-studio/docker/docker-compose.yml）：

将MySQL对外暴露端口改为一个不存在的端口（比如3307）即可。其他类似端口冲突问题，按照同样方式解决。

2、[MY-012960] [InnoDB] Cannot create redo log files because data files are corrupt or the database was not shut down cleanly after creating the data files.

这个错误来自 MySQL 的 InnoDB 存储引擎，说明 MySQL 启动失败。删除已有的数据文件，重新初始化（适用于开发环境或可清除数据场景）

改进步骤：

1、清空coze-studio/docker/data目录内的文件

3、Container coze-elasticsearch-setup service "elasticsearch-setup" didn... service "elasticsearch-setup" didn't complete successfully: exit 127

进入该容器发现找不到setup_es.sh 这个文件，实际这个文件存在的。使用代码编辑器（如 VS Code或Notepad++）打开 elasticsearch-setup 服务所依赖的启动脚本(coze-studio/docker/volumes/elasticsearch/setup_es.sh)。在编辑器的右下角，你会看到 CRLF 或 LF 的标识，点击它并选择 LF。保存文件后再重新启动就解决了。

通问AI硅基学院

通问AI硅基学院是通问AI旗下专注于企业AI精英人才培养与企业AI智能体设计的AI学院。提供面向全国的AI专业人才培养与AI智能体定制服务。