本教程将带你全面了解字节跳动开源的 Coze Studio（扣子开发平台），从核心功能解析到本地部署与模型配置，手把手教你搭建属于自己的智能体开发环境。无论你是AI开发者还是技术爱好者，都能通过这份指南快速上手，开启智能体开发的探索之旅。
一、Coze Studio 简介与核心功能
Coze Studio 源自 扣子开发平台，是一个一站式 AI 智能体开发平台。通过其提供的可视化设计与编排工具，开发者可以通过 零代码或低代码 的方式，快速打造和调试智能体、应用和工作流，实现强大的 AI 应用开发和定制化业务逻辑。
核心功能一览
模型服务：管理模型列表，可接入 OpenAI、火山方舟等在线或离线模型服务；
搭建智能体：编排、发布、管理智能体，支持配置工作流、知识库等资源；
搭建应用：创建、发布应用，通过工作流搭建业务逻辑；
搭建工作流：创建、修改、发布、删除工作流；
开发资源：支持创建并管理以下资源：插件、知识库、数据库、提示词；
API 与 SDK：创建会话、发起对话等 OpenAPI，通过 Chat SDK 将智能体或应用集成到自己的应用；
小提示：本次开源包括 Coze Studio（扣子开发平台） 和 Coze Loop（扣子罗盘） 两个核心项目，均采用 Apache 2.0 许可协议，这意味着你可以自由修改甚至闭源商用，极大地降低了企业级智能体开发的门槛。
二、本地部署详细步骤
Coze Studio 提供了完整的 Docker 镜像，使用 Docker Compose 即可快速部署。无需复杂配置，跟随以下步骤即可在本地运行起来。
1. 克隆源码
$ git clone https://github.com/coze-dev/coze-studio.git
2. 进入 docker 目录
$ cd coze-studio/docker
docker-compose.yml 文件定义了部署 Coze 包含的所有组件，主要分为三类：
核心数据存储与缓存
coze-mysql- MySQL 结构化数据存储coze-redis- Redis 缓存coze-elasticsearch- Elasticsearch 存储coze-minio- Minio 对象存储coze-milvus- Milvus 向量数据库coze-etcd- Milvus 依赖 etcd 管理元数据
消息中间件（基于 NSQ）
coze-nsqd- 负责接收、排队和向客户端投递消息coze-nsqlookupd- 管理拓扑信息，提供服务发现功能coze-nsqadmin- Web UI，用于查看集群统计信息并执行管理任务
初始化组件
coze-minio-setup- 导入图标类资源文件coze-mysql-setup-schema- 使用 Atlas 工具根据 HCL 文件创建数据库表结构coze-mysql-setup-init-sql- 使用 MySQL 原生客户端执行 SQL 脚本导入初始数据
另外，coze-server 是 Coze 的后端服务，负责处理所有业务逻辑。
❓ 常见问题：为什么有两个初始化 MySQL 的服务？
答案：这是为了兼容不同的部署方式。可能是项目正在逐步从传统 SQL 迁移到 Atlas 管理，因此同时保留了两个初始化路径。在实际部署中，两个服务都会按顺序执行，互不冲突。
3. 配置环境变量
将 .env.example 复制为 .env 文件：
$ cp .env.example .env
如果你需要修改数据库用户名、密码等，可以编辑 .env 文件。默认情况下无需修改，直接使用即可。
4. 启动所有容器
$ docker compose --profile "*" up -d
等待所有容器启动完毕。其中 coze-minio-setup、coze-mysql-setup-schema、coze-mysql-setup-init-sql 这几个初始化容器完成工作后会退出，处于 Exited 状态，这是 正常现象，不必担心。
5. 访问 Coze Studio 并注册
打开浏览器访问 http://localhost:8888/，即可看到 Coze Studio 页面。输入邮箱和密码进行注册，进入工作空间。
小提示：如果无法访问，请检查 Docker 容器是否全部正常运行。可以使用 docker ps 查看运行状态，确保 coze-server 处于 Up 状态。
三、配置模型服务
Coze Studio 是基于大模型的 AI 开发平台，必须配置模型服务才能正常创建智能体。模型配置采用 YAML 文件 统一管理，存放在 backend/conf/model 目录中。
1. 查看模板文件
Coze Studio 在 backend/conf/model/template 目录下提供了常见模型的模板：
$ tree backend/conf/model/template backend/conf/model/template ├── model_template_ark.yaml ├── model_template_ark_doubao-1.5-lite.yaml ├── model_template_ark_doubao-1.5-pro-256k.yaml ├── model_template_ark_doubao-1.5-pro-32k.yaml ├── model_template_ark_doubao-1.5-thinking-pro.yaml ├── model_template_ark_doubao-1.5-thinking-vision-pro.yaml ├── model_template_ark_doubao-1.5-vision-lite.yaml ├── model_template_ark_doubao-1.5-vision-pro.yaml ├── model_template_ark_doubao-seed-1.6-flash.yaml ├── model_template_ark_doubao-seed-1.6-thinking.yaml ├── model_template_ark_doubao-seed-1.6.yaml ├── model_template_ark_volc_deepseek-r1.yaml ├── model_template_ark_volc_deepseek-v3.yaml ├── model_template_basic.yaml ├── model_template_claude.yaml ├── model_template_deepseek.yaml ├── model_template_gemini.yaml ├── model_template_Ollama.yaml ├── model_template_openai.yaml └── model_template_qwen.yaml
除了字节自家的豆包（ARK 表示火山方舟），还内置了 OpenAI、DeepSeek、Claude、Ollama、Qwen、Gemini 等常见模型的支持。
2. 选择并复制模板
以魔搭平台上的 Qwen3-Coder 为例（兼容 OpenAI 接口），我们使用 OpenAI 模板：
$ cp backend/conf/model/template/model_template_openai.yaml backend/conf/model/model_modelscope_qwen3_coder.yaml
3. 修改关键参数
编辑复制后的 YAML 文件，重点关注以下参数：
id- 模型 ID，必须为非零整数且全局唯一，定义后建议不要修改；name- 模型在平台上展示的名称；description- 简介（分中英文）；default_parameters- 默认参数（temperature、max_tokens 等，一般无需改动）；meta.capability- 模型具备的能力（function call、json mode、reasoning、多模态等）；meta.conn_config.base_url- 模型服务接口地址，非 OpenAI 官方接口时需修改；meta.conn_config.api_key- API Key；meta.conn_config.model- 模型名，不同厂商命名不同，例如魔搭上为Qwen/Qwen3-Coder-480B-A35B-Instruct；meta.conn_config.openai.by_azure- 设置为false。
修改后的配置文件示例（关键部分）：
# 实际内容请参考原模板，此处仅示意关键参数
meta:
conn_config:
base_url: "https://api.modelscope.cn/v1"
api_key: "你的 API Key"
model: "Qwen/Qwen3-Coder-480B-A35B-Instruct"
openai:
by_azure: false
小提示：更多参数介绍请参考官方文档的 模型配置说明。不同模型服务商可能要求不同的字段，建议仔细阅读模板中的注释。
4. 重启服务使配置生效
$ docker compose --profile "*" restart coze-server
5. 验证模型服务
回到 Coze Studio 页面，点击“创建智能体”，在下拉列表中应该能看到刚配置的模型。选择该模型，在右侧“预览与调试”面板中发送消息测试，如果模型正常回复，说明配置成功。
❓ 常见问题：创建智能体时提示“模型不可用”怎么办？
答案：首先检查配置文件中的 base_url、api_key、model 是否填写正确。然后确认模型服务端是否可达（例如魔搭 API 需要网络通）。最后可以查看 coze-server 的日志：docker logs coze-server，根据错误信息排查。如果问题仍存在，尝试重启整个 Compose 服务：docker compose --profile "*" down && docker compose --profile "*" up -d。
四、总结与下一步
通过本教程，你已经完成了 Coze Studio 的本地部署，并成功配置了模型服务。现在，你可以开始自由地创建智能体、应用和工作流，探索 AI 智能体开发的无限可能。
如果你是首次接触 Coze，建议从创建简单的智能体开始，逐步尝试工作流编排、插件集成等高级功能。结合开源代码，你还可以深入了解其内部实现，甚至贡献自己的代码。
让我们一起开启 Coze 智能体的探索之旅吧！