---
name: agent-install
description: "安装或升级 Sophclaw Agent（含占位替换、备份、post_install 脚本与自动安装 skill）。用户要求安装/升级/重置 Agent 时使用。"
---

# Agent Install

安装、升级或重置**单个** Sophclaw Agent。本 skill 只做**顺序编排 + 调用脚本**，一次只装一个 Agent，禁止并行。

## 对话约束

- 勿对用户念内部状态枚举；安装状态以脚本输出的 **`user_prompt`** 为准
- 凡提示已备份，须给出 **`backup_dir` 完整路径**
- 密钥勿在公开渠道展示

---

## Step 1：选定 Agent 并获取安装包

**A. 解析 agent_id**

```bash
uv run {baseDir}/scripts/list_agents.py
```

非精确 id 时：

```bash
uv run {baseDir}/scripts/list_agents.py --query "{user_input}" --limit 5
```

候选多时让用户选；未匹配到则请用户重述。

**B. 下载并校验**

```bash
npx -y sophhub@latest agent download {agent_id} --path=/home/node/.openclaw/workspace
```

```bash
uv run {baseDir}/scripts/verify_download.py \
  --agent-id "{agent_id}" \
  --path "/home/node/.openclaw/workspace"
```

校验失败则 **终止**。

---

## Step 2：参数、占位替换与安装状态检测

依次执行，勿插入无关步骤。

**1）解析安装参数**

```bash
uv run {baseDir}/scripts/resolve_install_params.py \
  --agent-id "{agent_id}" \
  --path "/home/node/.openclaw/workspace"
```

确认 `openclaw_id`、`workspace`、`agent_name`。有 `placeholder_catalog` 时让用户确认替换文案，用户可覆盖默认值。

**2）按需替换 .md 中的占位符**（有 `placeholders` 时）

```bash
uv run {baseDir}/scripts/update_agent_md.py \
  --agent-id "{agent_id}" \
  --path "/home/node/.openclaw/workspace" \
  --replace "{{占位符}}=替换文案"
```

**3）检测安装状态**

```bash
uv run {baseDir}/scripts/check_installed.py \
  --agent-id "{agent_id}" \
  --source-path "/home/node/.openclaw/workspace" \
  --openclaw-id "{openclaw_id}" \
  --workspace "{workspace}" \
  --name "{agent_name}"
```

状态说明（用 `user_prompt` 转述，勿念内部枚举）：

- 缺依赖 Agent → 提示先装依赖，**终止**
- 可升级 → 先备份再覆盖
- 同版本 → 实为重置，须确认并先备份
- 未安装 → 直接进入 Step 3
- 配置异常 → **终止**

---

## Step 3：文件写入、post_install 与 Skill（openclaw.json 之前）

Step 2 非「缺依赖」/「配置异常」时继续。

**1）备份**（仅升级或重置）

先让用户回复「确认更新」或「确认重置」：

```bash
uv run {baseDir}/scripts/backup_agent.py \
  --agent-id "{agent_id}" \
  --openclaw-id "{current_openclaw_id}" \
  --workspace "{workspace}" \
  --status "{status}"
```

成功后告知 **`backup_dir` 完整路径**。新装跳过备份。

**2）拷贝文件到 workspace**

```bash
uv run {baseDir}/scripts/copy_agent_files.py \
  --agent-id "{agent_id}" \
  --path "/home/node/.openclaw/workspace" \
  --workspace "{workspace}"
```

**3）执行 post_install 脚本**

```bash
uv run {baseDir}/scripts/run_post_install.py \
  --agent-id "{agent_id}" \
  --workspace "{workspace}"
```

读取 `{workspace}/.config.json` 中的 `post_install`，依次执行各条 `script`（注入 `WORKSPACE={workspace}`）。`delete_on_success: true` 的脚本成功后自动删除。任一失败则**终止**。

**4）安装 auto_install skill**

```bash
uv run {baseDir}/scripts/install_agent_skills.py \
  --workspace "{workspace}"
```

对 `.config.json` 中 `auto_install: true` 的 skill 依次下载并替换 `{workspace}/skills/{name}` 目录。

---

## Step 4：更新 openclaw.json（最后执行）

Step 3 全部成功后写入：

```bash
uv run {baseDir}/scripts/update_openclaw.py \
  --agent-id "{agent_id}" \
  --source-path "/home/node/.openclaw/workspace" \
  --openclaw-id "{openclaw_id}" \
  --workspace "{workspace}" \
  --name "{agent_name}"
```

脚本自动处理 `auto_generate_image_description`、`heartbeat`（仅当 `.config.json` 显式配置时写入）、`bot-api` 账号等，输出中包含对应字段便于核对。

完成后汇总：agent_id、结果（新装/升级/重置）、workspace、备份目录、skill 列表、bot-api（密钥走安全渠道）。

---

## 错误与中止

```text
❌ 流程中止：<步骤> — <原因> — <建议>
```

同版须先确认再备份；本地版本更高勿强退；无 `openclaw.json` 先初始化。

## Forbidden

- 不要直接手改 `openclaw.json`
- 未确认前不要覆盖同名 Agent；未确认参数不要跑 `check_installed`
- 不要并行多 Agent；不要删其它 Agent 配置
- 勿把「下载成功」当成「已安装完成」
- 勿在本 skill 展开脚本实现细节
- **update_openclaw.py 必须在 Step 4 最后执行**，不得提前写入 openclaw.json