Coze 教程 第 2 章：Coze 开发环境搭建与配置
本文将手把手带你完成 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 已成功安装。
3. 获取 Coze 源码
Coze 的源代码托管在 GitHub 上，我们可以通过 git 命令获取：
打开终端（Docker Desktop 内置终端或系统终端）
执行以下命令克隆代码仓库：
⚠️ 注意：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 创建模型配置文件
进入模型配置目录：
复制 DeepSeek 模板文件：
4.2 编辑模型配置
用文本编辑器打开新创建的 deepseek-r1.yaml 文件，修改以下参数：
其中 api_key 需要在 DeepSeek 平台申请。
以下是几种常见模型的配置参数参考：
提示：豆包模型的 API Key 来自火山引擎（字节的云服务平台），可以在 https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey 申请。
5. 启动 Coze 服务
完成模型配置后，就可以启动 Coze 服务了：
确保当前在 coze-studio/docker 目录中
执行以下命令启动服务：
这个命令的含义是：
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）：
或者修改 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 错误：
8. 进阶配置：更换模型
如果你想更换为其他模型（如切换到 Qwen），可以按照以下步骤操作：
复制模板文件到配置目录：
修改 qwen.yaml 内容：
重启服务生效：
9. 验证部署是否成功
完成所有步骤后，可以通过以下方式验证 Coze 是否成功部署：
访问 http://localhost:8888，能够看到 Coze 登录界面
注册账号并登录系统
尝试创建一个简单的智能体并进行对话测试
如果遇到"Something error: Internal server error"，可以通过查看日志排查问题：
10. 本章小结
本章详细介绍了 Coze 开发环境的搭建与配置过程，主要包括以下内容：
环境准备：安装 Docker 作为 Coze 运行的基础环境
获取源码：从 GitHub 克隆 Coze Studio 代码仓库
模型配置：配置 DeepSeek 或其他大语言模型作为智能体的核心引擎
服务启动：使用 Docker Compose 启动所有 Coze 服务
问题排查：解决部署过程中可能遇到的常见问题
验证测试：访问 Coze 界面并验证部署是否成功
现在你已经成功搭建了本地的 Coze 开发环境，可以开始创建和测试自己的 AI 智能体了。在下一章中，我们将深入介绍如何使用 Coze 创建你的第一个智能体，并配置其基本功能和特性。
温馨提示：火山引擎等平台提供的免费 API 调用额度是有限的，请注意你的 token 消耗情况。你也可以配置本地模型或其他第三方模型服务，只需修改相应的 base_url 即可。
专注于软件测试开发 2022-08-29 加入
霍格沃兹测试开发学社，测试人社区：https://ceshiren.com/t/topic/22284
评论