# 问题排查指南

> 你是 AI Agent，此文档指导你如何处理用户遇到的问题。

---

## 安装问题

### npm install 失败

**执行检查：**
```bash
node --version
npm --version
```

**判断并处理：**

| 情况 | 你的行动 |
|------|----------|
| Node.js 版本 < v18 | 告知用户升级 Node.js |
| 网络连接错误 | 建议使用镜像源 |
| 权限错误 | 建议使用管理员权限 |

**镜像源命令：**
```bash
npm install -g opclawtm --registry=https://registry.npmmirror.com
```

---

### 命令不存在

**执行检查：**
```bash
npm config get prefix
```

**告知用户：**
- npm 全局安装路径未添加到 PATH
- 需要将路径添加到系统环境变量

---

## 授权问题

### trial-activate 提示已使用

**向用户说明：**
- 同一设备只能激活一次试用
- 如需继续使用：
  - 访问 https://opclawtm.com 购买授权
  - 抖音私信 1594204110 获取测试码

---

### 授权状态无效

**执行命令：**
```bash
opclawtm license-status
```

**判断并处理：**

| 情况 | 你的行动 |
|------|----------|
| 授权已过期 | 告知用户购买授权或获取测试码 |
| 授权信息损坏 | 建议用户重新绑定 |

---

## TUI 操作问题

### 系统初始化失败

**执行检查：**
```bash
opclawtm license-status
```

**向用户说明：**
- 检查授权是否有效
- 如授权无效，先完成授权绑定

---

### 团队创建卡住

**向用户说明：**
- 按 Esc 返回上级菜单
- 重新进入团队创建向导

---

### ID 输入问题

**向用户说明：**
- **所有 ID 直接回车自动填充**
- 不要手动输入 ID
- 自动生成的 ID 是英文格式，避免飞书崩溃

---

## 飞书配置问题

### 配对码未返回

**向用户确认：**
1. 是否完成了版本保存？
2. 飞书应用是否已上线？
3. Gateway 是否已启动？

**引导用户检查：**
- 在飞书开放平台确认应用状态
- 确认「使用长连接接收事件」已开启
- 确认 `im.message.receive_v1` 事件已添加

---

### Bot 绑定失败

**向用户说明：**
- 检查 App ID 格式（cli_开头）
- 检查 App Secret 是否正确
- 确认机器人能力已启用

---

### 群绑定失败

**向用户说明：**
- 检查群 ID 格式（oc_开头）
- 确认 Bot 已添加到群
- 在 TUI 中重新绑定

---

### 用户 ID 找不到

**执行查找：**
```bash
cat ~/.openclaw/logs/gateway.log | grep "ou_"
```

**向用户反馈：**
- 找到 `ou_` 开头的 ID
- 直接显示给用户

---

## Skill 创建问题

### 任务未创建

**向用户说明：**
- 确认总助理 ID 是否正确
- 确认需求说明已发送给飞书总助理
- 等待总助理创建任务

---

### Skill 未生效

**向用户说明：**
- 检查任务是否完成
- 打开总助理的 `workspace/skills/` 目录
- 确认 Skill 文件夹是否存在

---

## 联系支持

| 渠道 | 地址 |
|------|------|
| 官网 | https://opclawtm.com |
| 抖音 | 1594204110（私信获取支持） |