本文将手把手带你完成 Coze 开发环境的搭建与配置，让你能快速开始本地化的 AI 智能体开发。
1. Coze 开源概述与环境准备
字节跳动于 2025 年 7 月 26 日正式开源其 AI 智能体开发平台"扣子"（Coze），包含 Coze Studio 可视化开发工具和 Coze Loop 运维管理系统两大核心组件。它采用 Apache 2.0 许可证，允许免费商业使用，无隐藏条款。
1.1 硬件要求
Coze 的硬件要求非常亲民：
CPU：2 核或以上
内存：4GB 或以上
存储空间：至少 2GB 可用空间
这意味着普通家用电脑即可流畅运行，真正将 AI 开发门槛拉低到"家用电脑级"。
1.2 软件依赖
Coze 本地部署的唯一前置依赖是 Docker，它的作用是为 Coze 创建隔离的运行环境，避免了繁琐的环境配置工作。
2. 安装 Docker
Docker 是容器化平台，允许你轻松打包、分发和运行应用程序。
2.1 安装步骤
访问 Docker 官网下载适合你操作系统的安装包。
双击安装包，按照向导完成安装（Windows 用户需要启用 Hyper-V 功能，安装过程中若提示重启请同意）。
安装完成后打开 Docker Desktop，确认状态栏显示"Running"。
提示：如果从 Docker 官网下载速度慢，可以使用国内镜像包。
2.2 验证安装
安装完成后，打开终端或命令提示符，运行以下命令验证 Docker 是否安装成功：
docker --version
docker compose version如果这两个命令都能正确输出版本信息，说明 Docker 已成功安装。
3. 获取 Coze 源码
Coze 的源代码托管在 GitHub 上，我们可以通过 git 命令获取：
打开终端（Docker Desktop 内置终端或系统终端）
执行以下命令克隆代码仓库：
# 克隆Coze Studio代码仓库
git clone https://github.com/coze-dev/coze-studio.git
# 进入docker配置目录
cd coze-studio/docker
# 复制环境配置文件
cp .env.example .env⚠️ 注意：Windows 用户如果使用命令提示符（CMD），可能需要将 cp 命令替换为 copy：copy .env.example .env
对于不熟悉 git 的用户，可以直接在 GitHub 下载 ZIP 压缩包并解压，然后手动进入 coze-studio/docker 目录创建.env 文件。
4. 配置模型服务（关键步骤）
这是最关键的一步，不配置模型将无法创建智能体。Coze 支持多种大语言模型，包括 DeepSeek、OpenAI、Claude、Qwen、Gemini、豆包等。以下以配置 DeepSeek 模型为例：
4.1 创建模型配置文件
进入模型配置目录：
# Mac/Linux用户
open ../backend/conf/model/
# Windows用户
start ../backend/conf/model/复制 DeepSeek 模板文件：
# 复制DeepSeek模板
cp ../backend/conf/model/template/model_template_ark_volc_deepseek-r1.yaml backend/conf/model/deepseek-r1.yaml4.2 编辑模型配置
用文本编辑器打开新创建的 deepseek-r1.yaml 文件，修改以下参数：
base_url: "https://api.deepseek.com/v1"
api_key: "sk-xxxxxxxx" # 在DeepSeek平台(https://platform.deepseek.com/)申请
model: "deepseek-reasoner"其中 api_key 需要在 DeepSeek 平台申请。
以下是几种常见模型的配置参数参考：
提示：豆包模型的 API Key 来自火山引擎（字节的云服务平台），可以在 https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey 申请。
5. 启动 Coze 服务
完成模型配置后，就可以启动 Coze 服务了：
确保当前在 coze-studio/docker 目录中
执行以下命令启动服务：
docker compose --profile '*' up -d这个命令的含义是：
docker compose：使用 Docker Compose 运行服务
--profile '*'：启用所有 profile 配置
up：启动服务（没有就创建容器，有就重启）
-d：detached 模式，即在后台运行
首次运行需要下载和构建镜像，可能需要 5-15 分钟（具体时间取决于网络速度）。
6. 访问 Coze 界面
服务启动成功后，打开浏览器访问 http://localhost:8888，你就可以看到 Coze Studio 的首页了。
首次访问时，系统会提示你注册账号，输入任意邮箱和密码即可完成注册并登录系统。
7. 避坑指南：常见问题与解决方案
在部署过程中，可能会遇到一些常见问题，以下是解决方案：
7.1 端口冲突错误
如果启动时提示 Ports are not available，说明有端口被占用：
解决方案：
关闭占用端口的程序（如 3306/6379）：
# Windows查找占用3306端口的进程
netstat -ano | findstr :3306
# 然后使用任务管理器结束对应PID的进程或者修改 docker-compose.yml 中的端口映射配置，将冲突的端口改为其他未占用端口。
7.2 MySQL 启动失败
如果报错 MYSQL_USER cannot be "root"：
解决方案：
删除系统环境变量中的 MYSQL_USER 和 MYSQL_PASSWORD。
7.3 Elasticsearch 启动失败
如果报错 exit 127 或提示"service 'elasticsearch-setup' didn't complete successfully"：
解决方案：
用 VS Code 或 Notepad++等代码编辑器打开 docker/volumes/elasticsearch/setup_es.sh 文件。
在编辑器的右下角，你会看到 CRLF 或 LF 的标识，点击它并选择 LF 格式。
保存文件后重新启动服务。
7.4 Windows 特有问题
Windows 用户可能会遇到以下问题：
命令不存在错误：Windows 系统可能不支持一些 Linux 命令（如 cp、open 等）：
使用 copy 代替 cp
使用 start 代替 open
端口被系统保留：如果出现 Ports are not available: exposing port TCP 0.0.0.0:2379 错误：
# 查看端口占用
netstat -ano | findstr :2379
# 重置网络适配器
net stop winnat
net start winnat8. 进阶配置：更换模型
如果你想更换为其他模型（如切换到 Qwen），可以按照以下步骤操作：
复制模板文件到配置目录：
cp ../backend/conf/model/template/model_template_basic ../backend/conf/model/qwen.yaml修改 qwen.yaml 内容：
id: 2 # 保持唯一性，不可与其他模型重复
name: "qwen3-235b"
meta.conn_config:
base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
api_key: "阿里百炼申请的KEY"
model: "qwen3-235b-a22b-instruct-2507"重启服务生效：
docker compose --profile '*' restart coze-server9. 验证部署是否成功
完成所有步骤后，可以通过以下方式验证 Coze 是否成功部署：
访问 http://localhost:8888，能够看到 Coze 登录界面
注册账号并登录系统
尝试创建一个简单的智能体并进行对话测试
如果遇到"Something error: Internal server error"，可以通过查看日志排查问题：
# Linux/Mac
docker logs coze-server | grep -i 'node execute failed'
# Windows
docker logs coze-server | findstr /i "node execute failed"10. 本章小结
本章详细介绍了 Coze 开发环境的搭建与配置过程，主要包括以下内容：
环境准备：安装 Docker 作为 Coze 运行的基础环境
获取源码：从 GitHub 克隆 Coze Studio 代码仓库
模型配置：配置 DeepSeek 或其他大语言模型作为智能体的核心引擎
服务启动：使用 Docker Compose 启动所有 Coze 服务
问题排查：解决部署过程中可能遇到的常见问题
验证测试：访问 Coze 界面并验证部署是否成功
现在你已经成功搭建了本地的 Coze 开发环境，可以开始创建和测试自己的 AI 智能体了。在下一章中，我们将深入介绍如何使用 Coze 创建你的第一个智能体，并配置其基本功能和特性。
温馨提示：火山引擎等平台提供的免费 API 调用额度是有限的，请注意你的 token 消耗情况。你也可以配置本地模型或其他第三方模型服务，只需修改相应的 base_url 即可。
推荐学习
【霍格沃兹测试开发】7天软件测试快速入门 带你从零基础/转行/小白/就业/ 测试用例设计实战
【霍格沃兹测试开发】最新版！Web自动化测试从入门到精通/电子商务产品实战/Selenium（上集）
【霍格沃兹测试开发】最新版！Web自动化测试从入门到精通/电子商务产品实战/Selenium（下集）
【霍格沃兹测试开发】明星讲师精心打造最新Python教程软件测试开发从业者必学（上集）
【霍格沃兹测试开发】明星讲师精心打造最新Python教程软件测试开发从业者必学（下集）
【霍格沃兹测试开发】精品课合集/自动化测试/性能测试/精准测试/测试左移/测试右移/人工智能测试
【霍格沃兹测试开发】腾讯/百度/阿里/字节测试专家技术沙龙分享合集/精准化测试/流量回放/Diff
【霍格沃兹测试开发】Pytest用例结构/编写规范 /免费分享
【霍格沃兹测试开发】JMeter实时性能监控平台/数据分析展示系统Grafana/Docker安装
【霍格沃兹测试开发】接口自动化测试的场景有哪些？为什么要做接口自动化测试？如何一键生成测试报告？
【霍格沃兹测试开发】面试技巧指导/测试开发能力评级/1V1模拟面试实战/冲刺年薪百万！
【霍格沃兹测试开发】腾讯软件测试能力评级标准/要评级表格的联系我
【霍格沃兹测试开发】Pytest与Allure2一键生成测试报告/测试用例断言/数据驱动/参数化
【霍格沃兹测试开发】App功能测试实战快速入门/adb常用命令/adb压力测试
【霍格沃兹测试开发】阿里/百度/腾讯/滴滴/字节/一线大厂面试真题讲解，卷完拿高薪Offer！
【霍格沃兹测试开发】App自动化测试零基础快速入门/Appium/自动化用例录制/参数配置
【霍格沃兹测试开发】如何用Postman做接口测试，从入门到实战/接口抓包（最新最全教程）
【霍格沃兹测试开发】6小时轻松上手功能测试/软件测试工作流程/测试用例设计/Bug管理
【霍格沃兹测试开发】零基础小白如何使用Postman，从零到一做接口自动化测试/从零基础到进阶到实战
【霍格沃兹测试开发】建议收藏全国CCF测试开发大赛Python接口自动化测试赛前辅导 /项目实战
