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.yaml
4.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平台申请。
以下是几种常见模型的配置参数参考：
| 模型类型 | base_url | model参数 | API密钥来源 |
| DeepSeek | https://api.deepseek.com/v1 | deepseek-reasoner | DeepSeek平台 |
| OpenAI | https://api.openai.com/v1 | gpt-4 | OpenAI平台 |
| 豆包模型 | - | doubao-seed-1.6 | 火山引擎 |
| Qwen | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3-235b-a22b-instruct-2507 | 阿里百炼 |
💡 提示：豆包模型的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 winnat
8. 进阶配置：更换模型
如果你想更换为其他模型（如切换到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-server
9. 验证部署是否成功
完成所有步骤后，可以通过以下方式验证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即可。
精选文章：
国产模型Qwen3-32B本地化实战：LangChain + vLLM 构建企业智能引擎
零代码构建智能体！Dify插件打通AI Agent开发全链路
【保姆级教程】Dify+DeepSeek+MCP三件套：零门槛打造AI应用流水线，手把手实战教学！
10+热门 AI Agent 框架深度解析：谁更适合你的项目？
Kimi K2开源炸场，1万亿参数碾压GPT-4.1，成本仅Claude 4的1/5！
Playwright系列
Playwright 极速入门：1 小时搞定环境搭建与首个测试脚本
Playwright系列课（2） | 元素定位四大法宝：CSS/文本/XPath/语义化定位实战指南
Playwright自动化测试系列（3） | 第二阶段：核心技能与调试 交互操作大全
Playwright自动化测试系列课（4） | 异步加载克星：自动等待 vs 智能等待策略深度解析
Playwright自动化测试系列课（5） | 调试神器实战：Trace Viewer 录屏分析 + AI 辅助定位修复
Playwright 自动化测试系列（6）| 测试框架集成指南：参数化测试与多浏览器并行执行
Playwright 自动化测试系列（7）| 第三阶段：测试框架集成Page Object 模式
