本文将手把手带你完成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 安装步骤

1. 访问Docker官网下载适合你操作系统的安装包。

2. 双击安装包，按照向导完成安装（Windows用户需要启用Hyper-V功能，安装过程中若提示重启请同意）。

3. 安装完成后打开Docker Desktop，确认状态栏显示"Running"。

💡 提示：如果从Docker官网下载速度慢，可以使用国内镜像包。

2.2 验证安装

安装完成后，打开终端或命令提示符，运行以下命令验证Docker是否安装成功：

docker --version
docker compose version

如果这两个命令都能正确输出版本信息，说明Docker已成功安装。

3. 获取Coze源码

Coze的源代码托管在GitHub上，我们可以通过git命令获取：

1. 打开终端（Docker Desktop内置终端或系统终端）

2. 执行以下命令克隆代码仓库：

# 克隆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 创建模型配置文件

1. 进入模型配置目录：

   # Mac/Linux用户
   open ../backend/conf/model/
   
   # Windows用户
   start ../backend/conf/model/
   

2. 复制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服务了：

1. 确保当前在coze-studio/docker目录中

2. 执行以下命令启动服务：

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用户可能会遇到以下问题：

1. 命令不存在错误：Windows系统可能不支持一些Linux命令（如cp、open等）：

   • 使用copy代替cp

   • 使用start代替open

2. 端口被系统保留：如果出现Ports are not available: exposing port TCP 0.0.0.0:2379错误：

   # 查看端口占用
   netstat -ano | findstr :2379
   # 重置网络适配器
   net stop winnat
   net start winnat
   

8. 进阶配置：更换模型

如果你想更换为其他模型（如切换到Qwen），可以按照以下步骤操作：

1. 复制模板文件到配置目录：

   cp ../backend/conf/model/template/model_template_basic ../backend/conf/model/qwen.yaml
   

2. 修改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"
   

3. 重启服务生效：

   docker compose --profile '*' restart coze-server
   

9. 验证部署是否成功

完成所有步骤后，可以通过以下方式验证Coze是否成功部署：

1. 访问http://localhost:8888，能够看到Coze登录界面

2. 注册账号并登录系统

3. 尝试创建一个简单的智能体并进行对话测试

4. 如果遇到"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开发环境的搭建与配置过程，主要包括以下内容：

1. 环境准备：安装Docker作为Coze运行的基础环境

2. 获取源码：从GitHub克隆Coze Studio代码仓库

3. 模型配置：配置DeepSeek或其他大语言模型作为智能体的核心引擎

4. 服务启动：使用Docker Compose启动所有Coze服务

5. 问题排查：解决部署过程中可能遇到的常见问题

6. 验证测试：访问Coze界面并验证部署是否成功

现在你已经成功搭建了本地的Coze开发环境，可以开始创建和测试自己的AI智能体了。在下一章中，我们将深入介绍如何使用Coze创建你的第一个智能体，并配置其基本功能和特性。

温馨提示：火山引擎等平台提供的免费API调用额度是有限的，请注意你的token消耗情况。你也可以配置本地模型或其他第三方模型服务，只需修改相应的base_url即可。

---

推荐阅读

精选技术干货

精选文章

Docker

• Docker cp命令详解：在Docker容器和主机之间复制文件/文件夹

• Docker pull 命令详解：从镜像仓库获取镜像

• 深入理解 Docker Run 命令：从入门到精通

• Docker Exec 命令详解与实践指南

• Docker Kill/Pause/Unpause命令详细使用指南

• Docker Logs命令详解 1

Selenium

• 多任务一次搞定！selenium自动化复用浏览器技巧大揭秘

• 如何使用Selenium处理隐藏元素

• 软件测试/测试开发/全日制|selenium NoSuchDriverException问题解决

• 软件测试/人工智能|解决Selenium中的异常问题：“error sending request for url”

学社精选

• 测试开发之路 大厂面试总结 - 霍格沃兹测试开发学社 - 爱测-测试人社区
• 【面试】分享一个面试题总结，来置个顶 - 霍格沃兹测试学院校内交流 - 爱测-测试人社区
• 测试人生 | 从外包菜鸟到测试开发，薪资一年翻三倍，连自己都不敢信！（附面试真题与答案） - 测试开发 - 爱测-测试人社区
• 人工智能与自动化测试结合实战-探索人工智能在测试领域中的应用
• 爱测智能化测试平台
• 自动化测试平台
• 精准测试平台
• AI测试开发企业技术咨询服务

技术成长路线

系统化进阶路径与学习方案

• 人工智能测试开发路径
• 名企定向就业路径
• 测试开发进阶路线
• 测试开发高阶路线
• 性能测试进阶路径
• 测试管理专项提升路径
• 私教一对一技术指导
• 全日制 / 周末学习计划
• 公众号：霍格沃兹测试学院
• 视频号：霍格沃兹软件测试
• ChatGPT体验地址：霍格沃兹测试开发学社
• 霍格沃兹测试开发学社

企业级解决方案

测试体系建设与项目落地

• 全流程质量保障方案
• 按需定制化测试团队
• 自动化测试框架构建
• AI驱动的测试平台实施
• 车载测试专项方案
• 测吧（北京）科技有限公司

技术平台与工具

自研工具与开放资源

• 爱测智能化测试平台 - 测吧（北京）科技有限公司
• ceshiren.com 技术社区
• 开源工具 AppCrawler
• AI测试助手霍格沃兹测试开发学社
• 开源工具Hogwarts-Browser-Use

人工智能测试开发学习专区

• 人工智能/AI/为什么测试工程师需要掌握AI_哔哩哔哩_bilibili

• 人工智能在音频、视觉、多模态领域的应用_哔哩哔哩_bilibili

• 从0到1打造AI工作流：测试用例/测试架构图/测试报告/简历/PPT全自动生成

• 视觉识别在自动化测试中的应用-UI测试与游戏测试
  OpenAI Whisper 原理解析：如何实现高精度音频转文字_哔哩哔哩_bilibili

• 人工智能产品测试：从理论到实战
  专家系统与机器学习的概念_哔哩哔哩_bilibili

• AI驱动的全栈测试自动化与智能体开发
  基于LangChain手工测试用例生成工具_哔哩哔哩_bilibili

• 人工智能应用开发实战 ​LangChain+RAG+智能体全解析
  大语言模型应用开发框架 LangChain_哔哩哔哩_bilibili