开源AI工作流

快速开始

⚠️ 重要提示：TeamClaw 依赖 PostgreSQL 和 Redis，不支持单独 docker run 启动。请使用下面的 Docker Compose 方式部署。

方式一：Docker Compose 部署（推荐）

git clone https://github.com/szsip239/teamclaw.git
cd teamclaw
bash setup.sh

脚本会自动：

1. 生成 JWT 密钥对和加密密钥
2. 询问是否启用 Nginx HTTPS 反向代理（可选）
3. 通过 Docker Compose 启动 PostgreSQL、Redis 和 TeamClaw
4. 初始化数据库并创建默认管理员账号

访问 http://localhost:3100 — 账号：admin@teamclaw.local / Admin@123456

启用 HTTPS（可选）

setup.sh 会交互式询问是否启用 Nginx 反向代理。你也可以手动配置：

1. 将 SSL 证书文件放入 nginx/cert/ 目录 2. 编辑 .env 设置 Nginx 变量：

   NGINX_SERVER_NAME="your-domain.com"
   NGINX_SSL_CERT="your-cert.crt"
   NGINX_SSL_KEY="your-cert.key"
   

   docker compose -f docker-compose.prod.yml --profile nginx up -d
   

访问 https://your-domain.com

Docker 与 OpenClaw 实例

3. 部署 OpenClaw 实例

进入 实例管理 页面，选择以下任一方式：

Docker 容器（推荐） — 点击"创建实例"，选择 Docker 模式，填写实例名称，选择镜像（默认 alpine/openclaw:latest），点击创建即可自动部署。实例上线后会自动使用步骤 2 中你标记的默认资源与默认模型。

外部网关 — 如果已有运行中的 OpenClaw，选择外部网关模式，填入 WebSocket URL 和 Token 即可连接。已有模型配置的实例不会被覆盖，你可以通过 Config Editor 手动切换默认模型。

等待实例状态变为 🟢 ONLINE（通常 5-10 秒）。

5. 安装预置 Skills（可选）

v0.4.0 预置了 15 个开箱即用的参考 Skills，涵盖浏览器自动化、内容创作、数据分析、多搜索引擎等场景：

安装方法：进入 Skills 管理 页面 → 选择 skill → 点击"安装到实例" → 选目标实例 / agent / 安装路径（workspace 或 global）。

Option 1: Docker Compose (Recommended)

git clone https://github.com/szsip239/teamclaw.git
cd teamclaw
bash setup.sh

This will:

1. Generate JWT keys and encryption secrets
2. Ask whether to enable Nginx HTTPS reverse proxy (optional)
3. Start PostgreSQL, Redis, and TeamClaw via Docker Compose
4. Initialize the database with default admin account

Visit http://localhost:3100 — Login: admin@teamclaw.local / Admin@123456

Enable HTTPS (Optional)

setup.sh interactively asks whether to enable Nginx reverse proxy. You can also configure it manually:

1. Place SSL certificate files in nginx/cert/ 2. Edit .env to set Nginx variables:

   NGINX_SERVER_NAME="your-domain.com"
   NGINX_SSL_CERT="your-cert.crt"
   NGINX_SSL_KEY="your-cert.key"
   

   docker compose -f docker-compose.prod.yml --profile nginx up -d
   

Visit https://your-domain.com

Docker And OpenClaw Instances

Getting Started Guide

After deployment, follow these steps to start your first AI conversation:

3. Deploy an OpenClaw Instance

Navigate to the Instances page and choose one of:

Docker Container (Recommended) — Click "Create Instance", select Docker mode, enter a name, choose an image (default: alpine/openclaw:latest), and create. Once online, it automatically uses the default resource + default model you marked in Step 2.

External Gateway — If you already have a running OpenClaw, select external gateway mode, enter the WebSocket URL and token to connect. Existing model configurations are not overwritten — use the Config Editor to switch models if needed.

Wait for instance status to become 🟢 ONLINE (typically 5-10 seconds).

5. Install Pre-packaged Skills (Optional)

v0.4.0 ships with 15 ready-to-use reference skills covering browser automation, content creation, data analysis, multi-search, and more:

How to install: Open Skills → pick a skill → click "Install to Instance" → choose target instance / agent / install path (workspace or global).

首次使用指南

部署完成后，按以下步骤开始你的第一次 AI 对话：

Quick Start

⚠️ Important: TeamClaw requires PostgreSQL and Redis. Standalone docker run will NOT work. Use Docker Compose as described below.

Configuration Guide

Copy .env.example to .env, then fill in the required values. setup.sh generates secrets automatically; if you configure the project manually, run node scripts/generate-keys.mjs.

界面截图

仪表盘	AI 对话
Agent 管理	Skills 管理
实例管理	配置编辑器

Screenshots

Dashboard	AI Chat
Agent Management	Skills Marketplace
Instance Management	Config Editor

配置指南

复制 .env.example 为 .env 后，至少需要完成下面几类配置。setup.sh 会自动生成密钥；手动配置时请运行 node scripts/generate-keys.mjs。

配置校验

首次配置完成后建议按顺序执行：

npx prisma generate
npx prisma db push
npx tsx prisma/seed.ts
docker compose up -d
curl http://localhost:8000/api/health
npm run dev

如果知识库上传失败，优先检查 RAG_SERVICE_SECRET 是否一致、RAG_SERVICE_URL 是否能从 Next.js 所在环境访问、PADDLEOCR_TOKEN 是否有效，以及 SILICONFLOW_EMBEDDING_MODEL 和 PGVECTOR_EMBED_DIM 是否匹配。

2. 配置模型资源（**建议先做，再创建实例**）

进入 资源管理 页面，创建模型资源。我们支持 25 个内置 Provider，包括多区域 / 多计划 variants（例如 qwen 的"国内 Standard"、"国内 Coding Plan"、"国际 Standard"、"国际 Coding Plan"）：

完整支持 25 个 Provider（智谱 GLM、千帆、z.ai、Kimi Coding 等），详见资源管理页面。

操作流程：

1. 点击 创建资源 → 选择 Provider → 如有 variants，二级下拉选 region/plan → 填入 API Key → 保存
2. 进入资源详情 → Model 列表 → 点击其中一个模型右侧的 ⭐ 星标，将它设为"新实例默认模型"
3. 回到资源卡片，勾选 "设为默认"（让该 Resource 作为 provider 的首选 key）

为什么要先做这一步？ 从 v0.4.0 开始，teamclaw 会在新实例首次连接时自动把"默认 Resource + 默认模型"推送到实例配置里：

先配资源（设 ⭐ + "设为默认"）
   ↓
后创建实例
   ↓
实例首次 WebSocket 连接 → teamclaw 自动注入 models.providers + primary model
   ↓
开箱即用，无需在 Config Editor 手配

Option 2: Local Development

Two sub-modes —

A. Full Docker stack (recommended, zero local deps)

git clone https://github.com/szsip239/teamclaw.git
cd teamclaw
cp .env.example .env
node scripts/generate-keys.mjs            # writes JWT_*/ENCRYPTION_KEY etc.

docker compose --profile app up -d        # starts postgres + redis + rag + app
docker logs -f teamclaw-app               # watch Next.js Turbopack boot

Visit http://localhost:3100. Edits to src/** hot-reload; edits to rag-service/app/** trigger uvicorn --reload. --profile app is a switch: plain docker compose up -d only brings up the three infra services (postgres/redis/rag), letting host-mode users continue with B below.

B. Infra in Docker, Next.js on host

git clone https://github.com/szsip239/teamclaw.git
cd teamclaw
npm install

docker compose up -d                       # postgres + redis + rag (no app)

cp .env.example .env
node scripts/generate-keys.mjs

npx prisma generate
npx prisma db push
npx tsx prisma/seed.ts

npm run dev                                # Next.js on host (port 3100)

Host-side hot-reload is usually a touch faster (< 0.5s) — handy for pure frontend tweaks. data/knowledge-bases/ is shared between both modes, so uploaded docs survive a mode switch.

Configuration Check

After first-time setup, run:

npx prisma generate
npx prisma db push
npx tsx prisma/seed.ts
docker compose up -d
curl http://localhost:8000/api/health
npm run dev

If knowledge-base uploads fail, check that RAG_SERVICE_SECRET matches in both services, RAG_SERVICE_URL is reachable from the Next.js runtime, PADDLEOCR_TOKEN is valid, and SILICONFLOW_EMBEDDING_MODEL matches PGVECTOR_EMBED_DIM.

2. Configure Model Resources (**Do this BEFORE creating instances**)

Go to the Resources page to create model resources. 25 built-in providers are supported, including region/plan variants (e.g. qwen's "CN Standard", "CN Coding Plan", "Intl Standard", "Intl Coding Plan"):

25 providers supported (GLM, Qianfan, z.ai, Kimi Coding, etc.). See the Resources page for the full list.

Workflow:

1. Create Resource → pick a provider → if it has variants, pick one from the second-level dropdown → enter API key → save
2. Open the resource detail → Model list → click the ⭐ star next to one model to mark it as "default model for new instances"
3. Toggle "Set as default" on the resource card so this resource becomes the preferred key for its provider

Why do this first? Starting from v0.4.0, teamclaw automatically pushes your default resource + default model into every new instance on its first WebSocket connection:

Configure resources first (⭐ + "Set as default")
   ↓
Create an instance
   ↓
First WebSocket connect → teamclaw auto-injects models.providers + primary
   ↓
Works out of the box — no manual Config Editor setup needed

RAG 模型、Embedding 与 OCR

RAG 凭据有两种配置方式：

1. 推荐：登录后台，进入 知识库 页面，点击右上角 RAG 配置，填写 LLM、Embedding、Rerank、PaddleOCR。
2. 兜底：在 .env 中填写下面的变量。系统配置为空时会自动回退到环境变量。

当前项目默认模型栈：

模型选择建议：

如果你更换 Embedding 模型且维度不是 1024，需要先清理或迁移 rag schema 中的向量表，再修改 PGVECTOR_EMBED_DIM，否则查询会出现维度不匹配。