VAI TEAM Docs

Appearance

环境与模型准备 ​

本章目标：完成基本可用环境，理解模型配置和 Agent 的作用，为第一个项目做好准备。

预计时长：30 分钟

假设你已经按照 快速上手 完成了基础部署，现在开始配置使用环境。

登录系统 ​

首次登录 ​

  1. 打开浏览器，访问 http://localhost:8080
  2. 使用 .env 文件中配置的管理员账号登录
  3. 如果看到验证码，输入图片中显示的字符

忘记密码？

管理员密码在 .env 文件的 ADMIN_PASS 变量中。如需修改，编辑该文件后重启服务：docker compose restart

熟悉界面布局 ​

登录后你会看到：

  • 左侧导航栏：项目列表、模型管理、Agent 管理、帮助中心
  • 主工作区：当前页面内容
  • 右上角：用户信息、设置、退出

建议先点击各个菜单熟悉一下基本布局。

修改默认密码 ​

首次登录后强烈建议修改密码：

  1. 点击右上角头像
  2. 选择「改密码」
  3. 输入新密码（建议 8 位以上，包含字母数字）
  4. 确认修改

模型供应商配置 ​

理解模型的作用 ​

在 VAI TEAM 中，AI 模型是整个系统的"大脑"：

  • AI Leader 负责需求分析、架构设计、任务分解
  • 各角色 Agent 负责具体的编码、测试、部署工作

不同的工作需要不同能力的模型，合理配置能在质量和成本间找到平衡。

添加 DeepSeek（推荐起步） ​

DeepSeek 是性价比很高的选择，适合初学者：

  1. 进入「模型管理」页面
  2. 点击「添加供应商」
  3. 填写配置：
供应商名称：DeepSeek
Base URL：https://api.deepseek.com
API Key：sk-your-deepseek-api-key
  1. 点击「测试连接」
  2. 看到"连接成功"后点击「保存」
如何获取 DeepSeek API Key？
  1. 访问 DeepSeek 开放平台
  2. 注册账号并完成实名认证
  3. 进入控制台 → API 密钥
  4. 创建新的 API Key
  5. 复制密钥（注意保存，只显示一次）

新用户通常有免费额度，足够完成教程中的所有操作。

添加其他模型（可选） ​

如果你有其他模型的 API Key，也可以添加：

OpenAI：

供应商名称：OpenAI
Base URL：https://api.openai.com/v1
API Key：sk-your-openai-key

Anthropic（Claude）：

供应商名称：Anthropic
Base URL：https://api.anthropic.com
API Key：sk-ant-your-anthropic-key

模型选择建议

  • 只有 DeepSeek：全部角色都用 deepseek-chat
  • 有 OpenAI：Leader/Architect 用 gpt-4o，其他用 gpt-3.5-turbo
  • 有 Claude：Leader/Architect 用 claude-3-sonnet，其他用 DeepSeek

角色模型分配 ​

理解角色分工 ​

VAI TEAM 有 6 个内置角色，各有不同职责：

角色主要职责重要程度推荐模型等级
Leader需求分析、任务分解、项目协调⭐⭐⭐强模型
Architect技术架构、接口设计、数据库设计⭐⭐⭐强模型
Frontend前端页面、组件开发、样式实现⭐⭐中等模型
Backend后端 API、业务逻辑、数据处理⭐⭐中等模型
Tester测试用例、自动化测试、质量保证⭐轻量模型
DevOps部署脚本、环境配置、CI/CD⭐轻量模型

配置角色模型 ​

在「模型管理」→「角色配置」页面：

方案一：只有 DeepSeek

Leader：deepseek-chat
Architect：deepseek-chat  
Frontend：deepseek-coder（如果有）或 deepseek-chat
Backend：deepseek-coder（如果有）或 deepseek-chat
Tester：deepseek-chat
DevOps：deepseek-chat

方案二：混合配置（推荐）

Leader：gpt-4o 或 claude-3-sonnet
Architect：gpt-4o 或 claude-3-sonnet
Frontend：deepseek-chat
Backend：deepseek-chat  
Tester：deepseek-chat
DevOps：deepseek-chat

成本控制

决策型角色（Leader、Architect）用强模型能显著提升项目质量，但成本也更高。建议根据项目重要性灵活调整。

测试模型调用 ​

配置完成后，可以测试一下：

  1. 在角色配置页面点击「测试调用」
  2. 选择一个角色（如 Frontend）
  3. 输入简单测试 Prompt：请介绍一下你的职责
  4. 查看返回结果是否正常

认识 Agent ​

Agent 是什么 ​

Agent 是 VAI TEAM 的"执行手"：

  • 每个 Agent 运行在独立的 Docker 容器中
  • 拥有独立的 Git 工作区（/workspace）
  • 可以调用 AI 模型、执行 Git 操作、读写文件
  • 通过心跳机制与 Dispatcher 保持连接

查看 Agent 状态 ​

进入「Agent 管理」页面，你会看到：

字段说明正常值
状态在线/离线/忙碌🟢 在线
心跳时间最后一次汇报时间< 30 秒前
工作区路径Git 仓库位置/workspace/agent_xxx
当前任务正在执行的任务无（空闲状态）

处理 Agent 离线 ​

如果看到 Agent 显示离线（🔴），可以这样排查：

  1. 检查容器状态：

    bash
    docker compose ps

  2. 查看 Agent 日志：

    bash
    docker compose logs agent

  3. 重启 Agent：

    bash
    docker compose restart agent

  4. 检查网络连接：

    bash
    docker network ls
docker network inspect openclaw-team_default

Agent 工作时机

Agent 只在项目进入编码阶段（阶段 5）后才开始工作。前面的需求分析、架构设计等阶段由 Dispatcher 直接调用模型完成，不需要 Agent 参与。

环境验证清单 ​

在开始第一个项目前，确认以下项目都已完成：

✅ 基础环境 ​

  • [ ] 能正常访问控制台（http://localhost:8080）
  • [ ] 使用管理员账号成功登录
  • [ ] 修改了默认密码

✅ 模型配置 ​

  • [ ] 至少添加了一个模型供应商
  • [ ] 模型连接测试通过
  • [ ] 为所有角色分配了模型
  • [ ] 测试调用返回正常

✅ Agent 状态 ​

  • [ ] 至少有 1 个 Agent 显示在线
  • [ ] Agent 心跳时间正常（< 30 秒）
  • [ ] Agent 工作区路径存在

✅ 功能验证 ​

  • [ ] 能正常访问各个管理页面
  • [ ] 左侧导航菜单工作正常
  • [ ] 没有明显的错误提示

故障排查 ​

常见问题 ​

Q: 登录后页面空白或报错？

A: 检查浏览器控制台是否有 JavaScript 错误，尝试刷新页面或清除浏览器缓存。

Q: 模型连接测试失败？

A:

  1. 检查 API Key 是否正确
  2. 检查 Base URL 格式（需要包含 https://）
  3. 确认网络能访问模型供应商服务
  4. 查看 Dispatcher 日志：docker compose logs dispatcher

Q: Agent 一直显示离线？

A:

  1. 确认 Docker 容器正常运行：docker compose ps
  2. 检查容器间网络连通性
  3. 重启整个服务：docker compose down && docker compose up -d

Q: 界面显示异常或样式错乱？

A: 可能是浏览器兼容性问题，推荐使用 Chrome、Firefox 或 Edge 最新版本。

下一步 ​

环境准备完成后，你可以：

  1. 继续教程 — 创建第一个项目
  2. 深入了解 — 系统架构
  3. 配置优化 — 部署指南

建议

第一次使用建议先跟着教程走完整个流程，熟悉基本操作后再根据实际需求调整配置。

© 2026 VAI TEAM · 上海番茄信息技术有限公司