---
name: agent-provisioning
description: "新建 / 新增 / 创建 OpenClaw agent 的唯一正确流程。触发说法（中英皆可）：「新建 agent」「新建一个 agent」「新增 agent」「创建 agent」「加个 agent」「开一个 agent」「再来一个助手」「给某人开一个助手」「建个机器人」「加一个专属助理」以及 create a new agent / new agent / add an agent / create an assistant。流程为 agent 建专属 MySQL 库、专用账号、中文配置与 workspace，并禁止自行拼 SQL 建库。"
---

# 新建 agent（唯一正确流程）

## 何时使用
用户表达"新建 / 创建 / 增加一个 agent（助手 / 机器人 / 专属助理）"时。

## 唯一正确做法

```bash
bash ~/.openclaw/scripts/new-agent.sh <id> '<中文名>'
```

- `<id>`：ASCII，小写字母开头，只含 `[a-z0-9-]`，≤24 字符（例：`reading`）
- `<中文名>`：2–20 字符，不含空白（例：`阅读`）

先与用户确认这两个值，再执行。

**⚠️ 中文名必须用单引号包裹** —— 否则 `&`、空格等 shell 元字符会被解析。
实测教训：`bash new-agent.sh tchk 探针&巡检` 被 shell 拆成「后台执行 `… tchk 探针`」+「再执行 `巡检`」，
**意外触发了一次真实创建**。中文名还应尽量避免 `&` `/` `$` 与反引号。

**`--dry-run` 不是纯只读**：脚本会先做冲突检查，因此库/账号/agent 已存在时 `--dry-run` 同样会被拒绝（刻意设计，避免预览掩盖冲突）。


## 红线（禁止）

- ❌ 禁止自行拼 SQL 建库、建账号
- ❌ 禁止用 `mysql` / `docker exec` 直接操作数据库来创建 agent
- ❌ 禁止为建库读取或使用 root 凭据
- ❌ 禁止手工创建 `workspace-*` 目录或手改 `openclaw.json` 的 agents 条目

以上任一被绕过，都会造成"库存在但未被备份登记 / 账号缺失 / 配置中英混杂"的不一致。

## 执行后

脚本会输出四行结果（`DATABASE` / `USER` / `PASSWORD_ENV` / `WORKSPACE`）。
把结果转述给用户，并提示：新库将在**次日 03:00 自动进入每日备份**。

## 参数

| 参数 | 用途 |
|---|---|
| `--dry-run` | 只打印将执行的 SQL 与文件操作，不落地（先给用户看过再执行） |
| `--reset-password` | 仅重置已存在 agent 的账号密码（库/账号已存在时用） |