本地环境需满足docker≥24.0.0、启用wsl2/hyper-v；克隆coze-studio后校验docker-compose.yml及model/template目录完整性；配置ark_doubao-seed-1.6.yaml并填入api key与正确model id；执行docker compose up -d启动，curl http://localhost:8080/health返回{"status":"up"}且http://localhost:3000可登录admin/123456，settings中模型状态为active即成功。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
确认本地环境是否达标
你的电脑必须满足最低运行门槛，否则连项目启动都会报错退出。打开终端执行 docker --version 和 docker-compose --version，两项输出都必须有结果且版本不低于 24.0.0；若提示 command not found，说明 Docker 未安装或服务未启用，【必须先完成 Docker Desktop 安装并重启系统】。Windows 用户尤其注意：Hyper-V 或 WSL2 必须开启，否则容器根本拉不起来。
拉取 Coze Studio 源码并校验完整性
进入你习惯存放项目的目录，比如 ~/projects，然后执行：
git clone https://github.com/coze-dev/coze-studio.git
等待克隆完成。接着进入项目根目录：cd coze-studio。运行 ls -la 查看是否存在 docker-compose.yml 和 backend/conf/model/template/ 两个关键路径。如果 template 目录为空，说明 git-lfs 未安装或未生效，会导致模型配置文件缺失——这一步漏掉，后续所有部署都会卡在“找不到模型定义”错误上。
配置第一个可用大模型
Coze Studio 启动前必须指定至少一个模型配置文件，否则服务拒绝加载。当前最简路径是复用官方提供的 Ark Doubao 模板：
第一步：复制模板文件
cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml
第二步：编辑该 YAML 文件
用 VS Code 或其他编辑器打开 backend/conf/model/ark_doubao-seed-1.6.yaml，找到 meta.conn_config.api_key 字段，填入你已申请的 Ark 平台 API Key；再确认 id 值为非零整数（如 101），meta.conn_config.model 值为 doubao-pro-2505（此为 2026 年最新稳定版模型标识）。
⚠️ 注意：id 字段若为 0，系统会静默跳过该模型注册，前端创建 Bot 时将无法选择任何模型。
一键启动完整服务集群
确保你在 coze-studio 项目根目录下，直接运行：
docker compose up -d
等待约 90 秒，期间容器会自动拉取镜像、初始化数据库、加载插件。检查服务状态：docker compose ps，所有服务状态应显示为 running。最后验证后端是否就绪：curl http://localhost:8080/health，返回 {"status":"UP"} 即表示核心服务已激活。
登录并验证前端可访问
打开浏览器，访问 http://localhost:3000。首次加载可能需 20～30 秒，页面出现 Coze Studio 标志与“Create Bot”按钮即成功。使用默认账号登录：
【用户名：admin，密码：123456】
登录后点击右上角头像 → Settings → Model Providers，确认列表中已显示你刚配置的 ark_doubao-seed-1.6 条目，且状态为 Active。
