# ai-team

**Repository Path**: chazzorg/ai-team

## Basic Information

- **Project Name**: ai-team
- **Description**: AI Team - 基于 OpenClaw 的多 Agent 协作系统，支持快速部署和复制
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-18
- **Last Updated**: 2026-05-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# OpenClaw Memory Framework

基于 OpenClaw 的持久化长期记忆框架。

本项目不替代 OpenClaw，也不做独立 Agent 平台。它只补齐一条工程闭环：读取 OpenClaw 真实会话，提取有价值的信息，落盘保存，并在后续任务中召回复用。

## 项目定位

OpenClaw 负责运行时能力：

- Agent 运行
- 模型调用
- 渠道接入
- 会话生成

本项目负责长期记忆能力：

- 读取 OpenClaw 会话
- 清洗 transcript 并筛选候选记忆
- 使用 LLM 定稿，失败时回退 heuristic
- SQLite 与 Vault 双写持久化
- 去重、查询、统计和召回
- 生成可回注给后续任务的上下文

## 工作流程

```text
OpenClaw 会话
  -> transcript 清洗
  -> 规则初筛
  -> LLM 定稿
  -> heuristic fallback
  -> SQLite / Vault 持久化
  -> query / stats / recall
  -> 回注给后续 OpenClaw 任务
```

设计原则：

- 最小依赖 OpenClaw，只接入它已经提供的会话和运行时能力
- 持久化优先，长期记忆必须落盘
- 增量处理优先，只处理未处理会话
- 双写存储，SQLite 用于查询，Vault 用于可读归档
- 保守提取，宁可少存，也避免把闲聊和运行噪声写入长期记忆

## 目录结构

```text
config/                 项目源配置
config/channels/        飞书、钉钉等渠道配置
src/                    CLI、配置渲染、记忆提取、召回等核心代码
scripts/manage.sh       日常管理入口
workspace-templates/    可提交的 agent 工作区模板
workspaces/             本机 agent 工作区副本，默认不提交
runtime/                生成配置、数据库、Vault、日志等运行数据
tests/                  node:test 测试
vendor/sql.js/          内置 sql.js 依赖
```

## 配置说明

主要配置文件：

- [config/team.json](./config/team.json)：Gateway、agents、默认模型和运行参数
- [config/models.json](./config/models.json)：provider、模型列表和模型能力
- [config/memory.json](./config/memory.json)：ingest、dedupe、recall、embedding、storage 参数
- [config/automation.json](./config/automation.json)：项目内自动化任务声明
- [config/channels/feishu.json](./config/channels/feishu.json)：飞书账号与 agent 绑定
- [config/channels/dingtalk-connector.json](./config/channels/dingtalk-connector.json)：钉钉账号与 agent 绑定

运行时生成文件：

- [runtime/generated/openclaw.json](./runtime/generated/openclaw.json)：由源配置渲染生成，不要手动修改
- [runtime/data/memory.db](./runtime/data/memory.db)：SQLite 记忆库
- [runtime/vault](./runtime/vault)：可读归档
- [runtime/backups](./runtime/backups)：备份目录

## 环境要求

- Node.js `>= 18`
- 已安装 OpenClaw CLI
- 项目根目录存在 `.env`

常用环境变量：

- `AI_TEAM_GATEWAY_TOKEN`
- `DASHSCOPE_API_KEY`：百炼 Coding 平台，对应 `bailian-coding` provider；当前默认 agent 使用它。
- `BAILIAN_API_KEY`：原始百炼平台，对应 `bailian` provider；仅在模型引用 `bailian/...` 时需要。
- `DASHSCOPE_EMBEDDING_API_KEY`：语义召回 embedding 专用 key。
- `ARKCODE_API_KEY`：火山 Ark Code 平台，对应 `arkcode` provider；仅在模型引用 `arkcode/...` 时需要。
- `XIAOMI_CODING_API_KEY`：小米 MiMo Token Plan，对应 `xiaomi-coding` provider；仅在模型引用 `xiaomi-coding/...` 时需要。
- `OLLAMA_API_KEY`：Ollama 云端 OpenAI 兼容接口，对应 `ollama` provider；仅在模型引用 `ollama/...` 时需要，本地 `localhost:11434` 的 Ollama 不使用这个变量。
- `FEISHU_APP_ID`
- `FEISHU_APP_SECRET`
- `DINGTALK_CLIENT_ID`
- `DINGTALK_CLIENT_SECRET`
- `OPENCLAW_AGENTS_ROOT`

不是所有变量都必须同时配置。最小启动通常需要 `AI_TEAM_GATEWAY_TOKEN` 和当前默认模型对应的 API key；飞书、钉钉、embedding 只在启用对应能力时需要。

当前默认模型配置在 [config/team.json](./config/team.json)，默认指向 `xiaomi-coding/mimo-v2.5-pro`，因此最小启动需要配置 `XIAOMI_CODING_API_KEY`。如果改成百炼 Coding 模型，例如 `bailian-coding/glm-5`，再配置 `DASHSCOPE_API_KEY`。

## 快速开始

在项目根目录执行：

```bash
cp .env.example .env
```

编辑 `.env`，至少补齐：

- `AI_TEAM_GATEWAY_TOKEN`
- 当前默认模型所需的 API key；默认配置下是 `XIAOMI_CODING_API_KEY`

初始化 workspace 并渲染配置：

```bash
./scripts/manage.sh init-workspaces
./scripts/manage.sh bootstrap
```

预期结果：

- `workspaces/` 下生成本机 agent 工作区副本
- `runtime/generated/openclaw.json` 生成成功
- OpenClaw 配置校验通过
- `doctor` 返回健康状态

启动 Gateway：

```bash
./scripts/manage.sh gateway-run
```

需要后台运行时改用：

```bash
./scripts/manage.sh gateway-start
./scripts/manage.sh gateway-status
./scripts/manage.sh status
```

停止后台 Gateway：

```bash
./scripts/manage.sh gateway-stop
```

## 渠道接入

### 飞书

内置飞书渠道无需额外安装插件。

`.env` 至少需要：

- `FEISHU_APP_ID`
- `FEISHU_APP_SECRET`

如果使用多 agent 飞书账号，再配置：

- `FEISHU_BUILDER_APP_ID`
- `FEISHU_BUILDER_APP_SECRET`
- `FEISHU_REVIEWER_APP_ID`
- `FEISHU_REVIEWER_APP_SECRET`

注意：不要同时安装或启用第三方飞书扩展，例如 `openclaw-lark`，避免与内置 `feishu` 渠道冲突。

### 钉钉

钉钉需要安装 OpenClaw 插件：

```bash
openclaw plugins install @dingtalk-real-ai/dingtalk-connector
```

`.env` 至少需要：

- `DINGTALK_CLIENT_ID`
- `DINGTALK_CLIENT_SECRET`

启用前确认 [config/channels/dingtalk-connector.json](./config/channels/dingtalk-connector.json) 中 `enabled` 已打开。

当前群聊策略默认为 `groupPolicy: "allowlist"`。需要显式维护 `groupAllowFrom`，否则群聊中的 @mention 不会触发 agent。

## 记忆使用

先正常通过飞书、钉钉或 OpenClaw 与 agent 交互，再执行：

```bash
./scripts/manage.sh ingest
./scripts/manage.sh stats
./scripts/manage.sh query --limit 10
./scripts/manage.sh recall --agent coordinator --query "项目约定"
```

常见命令含义：

- `ingest`：处理未沉淀的 OpenClaw 会话
- `ingest-session <sessionId>`：处理指定 session
- `stats`：查看记忆库统计
- `query`：查询已存储记忆
- `recall`：生成可回注上下文
- `sync`：把 SQLite 中缺失的记忆补写到 Vault
- `review`：生成长期记忆整理候选文件，不直接改写 `MEMORY.md`

默认提取流程会调用 LLM 定稿。LLM 不可用时，会自动回退 heuristic 模式。

## 语义召回

语义召回配置位于 [config/memory.json](./config/memory.json)，当前使用独立 embedding endpoint，不复用 [config/models.json](./config/models.json) 中的聊天模型配置。

启用前在 `.env` 中配置：

- `DASHSCOPE_EMBEDDING_API_KEY`

补写历史 embedding：

```bash
node src/cli/index.js memory backfill-embeddings --limit 50
```

然后正常使用召回：

```bash
./scripts/manage.sh recall --agent coordinator --query "环境变量约定"
```

## 自动化

自动化声明位于 [config/automation.json](./config/automation.json)。

默认任务：

- `memory-ingest-pending`：每 10 分钟处理未沉淀会话
- `memory-sync`：每小时补写缺失 Vault 文件
- `memory-review-candidate`：每天生成长期记忆整理候选文件
- `health-check`：每小时检查项目状态

当前采用“项目内调度 + OpenClaw 单入口 cron”：

- OpenClaw 只保留一个 `project-scheduler`
- 它定时执行 `./scripts/manage.sh schedule-run`
- 具体 job 是否到期、是否跳过，由项目内 scheduler 判断

常用命令：

```bash
./scripts/manage.sh automation-show
./scripts/manage.sh automation-status
./scripts/manage.sh schedule-run
./scripts/manage.sh automation-install-openclaw
./scripts/manage.sh automation-remove-openclaw
```

## 配置变更约束

只修改源配置文件：

- `.env`
- [config/team.json](./config/team.json)
- [config/models.json](./config/models.json)
- [config/memory.json](./config/memory.json)
- [config/channels/feishu.json](./config/channels/feishu.json)
- [config/channels/dingtalk-connector.json](./config/channels/dingtalk-connector.json)
- [config/mcp.json](./config/mcp.json)

不要手动修改 [runtime/generated/openclaw.json](./runtime/generated/openclaw.json)。

配置改完后统一执行：

```bash
./scripts/manage.sh gateway-stop
./scripts/manage.sh render-config
./scripts/manage.sh gateway-start
```

启动完成并确认 channel `connect success` 后，再去飞书或钉钉里测试消息。

更换主模型时使用命令改源配置，命令会先检查目标模型是否存在于 [config/models.json](./config/models.json)，不存在会失败，不会写入配置：

```bash
./scripts/manage.sh set-main-model xiaomi-coding/mimo-v2.5-pro
```

预期输出中 `status` 为 `ok`，并显示 `previous`、`current`、`updatedAgents` 和 `renderedConfig`。如果模型不存在，命令会返回错误并列出当前可选模型。

该命令会更新 [config/team.json](./config/team.json) 中的 `agents.defaults.model`，并同步更新当前仍等于旧主模型的 agent `model` 字段，然后重新生成 [runtime/generated/openclaw.json](./runtime/generated/openclaw.json)。如果已有某个 agent 手动配置了不同模型，默认不会覆盖；确实要覆盖所有 agent 时可加 `--all-agents`。

更换主模型后，如果 Gateway 已在运行，按统一顺序重启：

```bash
./scripts/manage.sh gateway-stop
./scripts/manage.sh gateway-start
```

## 常用命令

| 命令 | 说明 |
| --- | --- |
| `./scripts/manage.sh help` | 查看所有可用管理命令。 |
| `./scripts/manage.sh init-workspaces` | 从 `workspace-templates/` 初始化本机 `workspaces/`，只补齐缺失文件，不覆盖已有文件。 |
| `./scripts/manage.sh bootstrap` | 一键执行初始化检查：加载 `.env`、渲染配置、校验配置并运行 `doctor`。 |
| `./scripts/manage.sh render-config` | 根据源配置生成 `runtime/generated/openclaw.json`。 |
| `./scripts/manage.sh validate-config` | 重新生成配置并校验 OpenClaw 配置是否有效。 |
| `./scripts/manage.sh doctor` | 查看项目健康状态，包括配置、会话源和记忆库状态。 |
| `./scripts/manage.sh set-main-model <provider>/<model>` | 校验并更换主模型，同时渲染生成配置。 |
| `./scripts/manage.sh gateway-run` | 前台启动 OpenClaw Gateway，适合本地联调和观察日志。 |
| `./scripts/manage.sh gateway-start` | 后台启动 OpenClaw Gateway，适合长期运行。 |
| `./scripts/manage.sh gateway-stop` | 停止后台运行的 OpenClaw Gateway。 |
| `./scripts/manage.sh gateway-status` | 查看 Gateway 服务状态和日志位置。 |
| `./scripts/manage.sh status` | 使用项目生成配置查看 OpenClaw 总状态。 |
| `./scripts/manage.sh sessions` | 列出各 agent 最近会话，用于确认会话是否已生成。 |
| `./scripts/manage.sh ingest` | 处理未沉淀的会话，提取并写入长期记忆。 |
| `./scripts/manage.sh ingest-session <sessionId>` | 处理指定 session，适合调试单条会话。 |
| `./scripts/manage.sh stats` | 查看记忆库统计信息。 |
| `./scripts/manage.sh query --limit 10` | 查询已存储记忆，默认按最近或匹配结果返回。 |
| `./scripts/manage.sh recall --agent coordinator --query "项目约定"` | 为指定 agent 生成召回上下文，可回注给后续任务。 |
| `./scripts/manage.sh sync` | 把 SQLite 中缺失的记忆补写到 Vault。 |

运行测试：

```bash
npm test
```

## 排障入口

最小排障命令：

```bash
./scripts/manage.sh gateway-status
./scripts/manage.sh status
./scripts/manage.sh sessions
```

如果需要查看 OpenClaw 原生命令的任务状态，建议显式带项目生成配置：

```bash
OPENCLAW_CONFIG_PATH=$PWD/runtime/generated/openclaw.json openclaw tasks audit
```

更完整的运行、维护和排障步骤见 [OPERATIONS.md](./OPERATIONS.md)。

## 文档分工

- [README.md](./README.md)：项目定位、快速开始、核心命令
- [OPERATIONS.md](./OPERATIONS.md)：日常运行、渠道配置、排障、维护操作