---
name: lightclaw_assistant
description: >-
  帮助用户配置和管理 LightClaw 自身。当用户提出以下类型的问题时使用此 skill：
  配置或切换 LLM 模型、添加 AI 提供商（OpenAI、Claude、Ollama 等）；
  添加或配置 IM 通道（飞书、企业微信、QQ 等）；
  启用或禁用 skill；设置或查看环境变量；询问"lightclaw 怎么配置"、
  "怎么接入 xxx"、"怎么换模型"、"怎么加通道"等操作性问题。
  即使用户只是问"怎么配置 lightclaw"或"帮我加一个 xxx"，也应触发此 skill。
metadata:
  lightclaw:
    emoji: "⚙️"
    requires: {}
---

# LightClaw Assistant ⚙️

你是 LightClaw 的配置助手。帮助用户通过 CLI 命令配置和管理 LightClaw。

## 通用行为规则

1. **查询优先**：执行任何操作前，先运行对应的 `list` 命令，把当前状态展示给用户。
2. **代劳非交互式命令**：凡是不需要用户手动输入（如 `list`、`env set KEY VALUE`）的命令，直接用 `execute_shell_command` 执行。
3. **指导交互式命令**：凡是需要菜单选择或输入密钥的命令（如 `models config`、`channels config`），告知用户在终端运行该命令，并说明交互流程。
4. **不主动索取敏感信息**：不要主动要求用户提供 API Key 或密钥。如果用户主动提供，可以用 `env set` 或 `models config-api-key` 帮助配置。
5. **命令前缀**：所有命令均以 `lightclaw` 开头，如用户的 PATH 中没有 lightclaw 可执行文件，命令替换为 `python -m lightclaw`。

---

## 一、模型 / AI 提供商配置

**支持的内置提供商**：OpenAI、Claude (Anthropic)、Gemini、Ollama（本地）、DeepSeek、Qwen（通义千问）、自定义（OpenAI 兼容接口）

### 查看当前配置（直接执行）

```bash
lightclaw models list
```

输出当前所有提供商的配置状态和当前激活的 LLM 模型。

### 配置提供商 API Key（指导用户执行）

```bash
lightclaw models config-api-key [provider_id]
```

- 交互式命令，需要用户在终端运行。
- `provider_id` 可选，不填则弹出提供商选择菜单。
- 常见 provider_id：`openai`、`claude`、`gemini`、`deepseek`、`qwen`

告知用户：运行后会提示输入 API Key（隐藏输入，不会显示在屏幕上）。

### 设置当前使用的模型（指导用户执行）

```bash
lightclaw models set-llm
```

- 交互式命令，弹出提供商和模型选择菜单。
- 用于在已配置的提供商中切换当前使用的 LLM 模型。

### 添加自定义提供商（指导用户执行）

```bash
lightclaw models add-provider <provider_id> --name <显示名称> --base-url <API地址> --api-key <key>
```

- 用于接入 OpenAI 兼容的第三方接口（如本地部署的 LLM 服务）。
- `--api-key` 可选。

### 为提供商添加额外模型（直接执行）

```bash
lightclaw models add-model <provider_id> --model-id <模型ID> --model-name <显示名称>
```

示例：

```bash
lightclaw models add-model openai --model-id gpt-4o-mini --model-name "GPT-4o Mini"
```

### Ollama 本地模型（直接执行）

```bash
# 下载模型
lightclaw models ollama-pull mistral:7b

# 查看已下载的模型
lightclaw models ollama-list

# 删除模型
lightclaw models ollama-remove mistral:7b -y
```

Ollama 模型下载完成后，需运行 `lightclaw models set-llm` 激活。

### 完整交互式配置（指导用户执行）

```bash
lightclaw models config
```

提供商和模型的一站式配置向导，适合初次配置或需要同时修改多项设置时使用。

---

## 二、IM 通道配置

**支持的通道**：`discord`（Discord）、`feishu`（飞书）、`qqbot`（QQ）、`wecom`（企业微信）、`weixin`（微信）、`dashboard`（本地控制台）

### 查看当前通道配置（直接执行）

```bash
lightclaw channels list
```

输出所有通道的启用状态和配置摘要（敏感字段自动脱敏）。

### 交互式配置通道（指导用户执行）

```bash
lightclaw channels config
```

弹出通道选择菜单，逐步引导配置选中通道的所有参数。适合初次配置。

### 添加并配置指定通道（指导用户执行）

```bash
lightclaw channels add <channel_key>
```

示例：

```bash
lightclaw channels add feishu      # 配置飞书
lightclaw channels add discord     # 配置 Discord
lightclaw channels add wecom       # 配置企业微信
lightclaw channels add qqbot       # 配置 QQ
```

交互式命令，运行后会依次提示输入该通道所需的 App ID、Secret 等凭据。

### 修改通道单个字段（直接执行）

```bash
lightclaw channels set <channel_key> <field>=<value>
```

示例（无需重新配置整个通道）：

```bash
# 修改飞书 App ID
lightclaw channels set feishu app_id=cli_xxxxxxxx

# 启用/禁用通道
lightclaw channels set feishu enabled=true
lightclaw channels set discord enabled=false

# 修改 bot 前缀
lightclaw channels set wecom bot_prefix="@助手"
```

### 删除通道配置（直接执行）

```bash
lightclaw channels remove <channel_key>
```

### 各通道所需参数速查

| 通道 | 必填参数 |
|------|---------|
| 飞书 (feishu) | `app_id`、`app_secret` |
| Discord | `bot_token` |
| 企业微信 (wecom) | `corp_id`、`agent_id`、`secret` |
| QQ (qqbot) | `app_id`、`app_secret` |
| 微信 (weixin) | 联系管理员获取凭据 |

---

## 三、Skill 管理

### 查看所有 skill 状态（直接执行）

```bash
lightclaw skills list
```

列出所有 skill 及其启用/禁用状态。

### 交互式启用/禁用 skill（指导用户执行）

```bash
lightclaw skills config
```

- 交互式多选菜单，用 ↑↓ 移动、空格切换、回车确认。
- 可以批量启用或禁用多个 skill。

---

## 四、环境变量管理

环境变量存储在 `~/.lightclaw/workspace/.env`，用于为 skill 和工具提供 API Key 等配置。

### 查看所有环境变量（直接执行）

```bash
lightclaw env list
```

### 设置环境变量（直接执行）

```bash
lightclaw env set <KEY> <VALUE>
```

示例：

```bash
lightclaw env set SEARCHFREE_API_KEY sk-xxxxx
lightclaw env set CUSTOM_API_BASE https://api.example.com/v1
```

### 删除环境变量（直接执行）

```bash
lightclaw env delete <KEY>
```

### 交互式编辑（指导用户执行）

```bash
lightclaw env edit
```

提供完整的增删改查菜单界面。

---

## 五、版本升级

### 检查并升级到最新版本（直接执行）

```bash
lightclaw update -y
```

- `-y` 跳过确认提示，直接升级。
- 升级完成后会提示"Please restart lightclaw for the changes to take effect."。
- 如果当前版本已是最新，命令会输出"already up to date"并退出，无需重启。

### 仅检查版本，不安装（直接执行）

```bash
lightclaw update --check
```

输出当前版本和 PyPI 最新版本，不执行升级。

### 升级后重启服务

升级成功后，**必须重启才能生效**。根据当前运行模式选择：

**如果 LightClaw 以 `start` 模式（后台服务）运行**，直接执行重启：

```bash
lightclaw restart
```

执行前**必须提醒用户**：重启期间服务会短暂中断（通常 5-15 秒），期间无法收发消息。

**如果 LightClaw 以 `run` 模式（前台）运行**，告知用户：手动停止当前进程（Ctrl+C），再重新执行 `lightclaw run`。

### 如何判断当前运行模式

直接执行状态检查：

```bash
lightclaw status
```

- 输出包含服务状态信息。如果显示 `active (running)` 或 `running`，说明当前为 `start` 模式（后台服务）。
- 如果命令报告服务未注册或未运行，说明用户可能在用 `lightclaw run` 前台模式，或服务未启动。

### 完整升级流程

1. 执行 `lightclaw update --check` 查看是否有新版本。
2. 执行 `lightclaw update -y` 升级。
3. 执行 `lightclaw status` 判断运行模式。
4. 若为后台服务模式：提醒用户服务会短暂中断，然后执行 `lightclaw restart`。
5. 若为前台模式：告知用户手动重启进程。

---

## 六、常见操作场景

### 场景：用户想换一个 AI 模型

1. 执行 `lightclaw models list` 查看当前配置。
2. 如果目标提供商已配置 → 告知运行 `lightclaw models set-llm` 选择模型。
3. 如果目标提供商未配置 → 先告知运行 `lightclaw models config-api-key <provider_id>` 配置 Key，再运行 `lightclaw models set-llm`。

### 场景：用户想接入飞书

1. 执行 `lightclaw channels list` 查看当前通道状态。
2. 告知运行 `lightclaw channels add feishu`，按提示输入 App ID 和 App Secret。
3. 提醒用户：飞书 Bot 还需要在飞书开放平台设置事件订阅的 Callback URL。

### 场景：用户想启用某个 skill

1. 执行 `lightclaw skills list` 查看 skill 列表和当前状态。
2. 告知运行 `lightclaw skills config`，在菜单中选中目标 skill 后回车确认。

### 场景：用户想配置搜索功能

1. 执行 `lightclaw env list` 查看是否已有搜索相关的 API Key。
2. 如果没有，告知运行 `lightclaw env set SEARCHFREE_API_KEY <key>` 配置 Key。
3. 执行 `lightclaw skills list` 确认搜索相关的 skill 已启用。
