# CLI 命令参考

LibreFang CLI 所有命令组的详细参考：Agent、Hand、工作流、触发器、技能、通道和配置。

有关 CLI 概述、安装说明和全局选项，请参阅 [CLI 参考](/zh/integrations/cli)。有关使用示例和指南，请参阅 [CLI 示例与指南](/zh/integrations/cli/examples)。

---

## Agent 命令

### librefang agent new

从内置模板生成 Agent。

```
librefang agent new [<TEMPLATE>]
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<TEMPLATE>` | 模板名称（如 `coder`、`assistant`、`researcher`）。如果省略，将显示交互式选择器列出所有可用模板。 |

**行为：**

- 从以下位置发现模板：仓库 `agents/` 目录（开发构建）、`~/.librefang/workspaces/agents/`（assistant 预装，其他模板从仪表板安装）、以及 `LIBREFANG_AGENTS_DIR`（环境变量覆盖）。
- 每个模板是一个包含 `agent.toml` 清单文件的目录。
- 守护进程模式下：发送 `POST /api/agents` 请求附带清单内容。Agent 将被持久化。
- 独立模式下：启动进程内核。Agent 是临时的。

**示例：**

```bash
# 交互式选择器
librefang agent new

# 按名称生成
librefang agent new coder

# 生成 assistant 模板
librefang agent new assistant
```

---

### librefang agent spawn

从自定义清单文件生成 Agent。

```
librefang agent spawn <MANIFEST>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<MANIFEST>` | Agent 清单 TOML 文件的路径。 |

**行为：**

- 读取并解析 TOML 清单文件。
- 守护进程模式下：将原始 TOML 发送到 `POST /api/agents`。
- 独立模式下：启动进程内核并在本地生成 Agent。

**示例：**

```bash
librefang agent spawn ./my-agent/agent.toml
```

---

### librefang agent list

列出所有正在运行的 Agent。

```
librefang agent list [--json]
```

**选项：**

| 选项 | 说明 |
|---|---|
| `--json` | 以 JSON 数组格式输出，便于脚本处理。 |

**输出列：** ID、NAME、STATE、PROVIDER、MODEL（守护进程模式）或 ID、NAME、STATE、CREATED（进程内模式）。

**示例：**

```bash
librefang agent list

librefang agent list --json | jq '.[].name'
```

---

### librefang agent chat

与指定 Agent 启动交互式聊天会话。

```
librefang agent chat <AGENT_ID>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<AGENT_ID>` | Agent UUID。可通过 `librefang agent list` 获取。 |

**行为：**

- 打开 REPL 风格的聊天循环。
- 在 `you>` 提示符处输入消息。
- Agent 回复显示在 `agent>` 提示符处，后跟令牌用量和迭代次数。
- 输入 `exit`、`quit` 或按 `Ctrl+C` 结束会话。

**示例：**

```bash
librefang agent chat a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

---

### librefang agent kill

终止正在运行的 Agent。

```
librefang agent kill <AGENT_ID>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<AGENT_ID>` | 要终止的 Agent UUID。 |

**示例：**

```bash
librefang agent kill a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

---

## Hand 管理

Hand 是自主执行模块，赋予 Agent 在真实世界中执行操作的能力 -- 浏览网页、管理文件、调用 API 等。所有 Hand 命令需要守护进程正在运行。

### librefang hand list

列出所有可用的 Hand（内置和已安装）。

```
librefang hand list
```

**输出列：** ID、NAME、VERSION、STATUS、DESCRIPTION。

从 `~/.librefang/workspaces/hands/`（首次启动时从注册表预装）发现 Hand。用户可以从仪表板激活 Hand。

---

### librefang hand active

显示当前活跃的 Hand 实例及其运行时状态。

```
librefang hand active
```

**输出列：** INSTANCE ID、HAND ID、AGENT、STATE、STARTED。

---

### librefang hand activate \<name\>

激活 Hand，使其可供 Agent 使用。

```
librefang hand activate <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID（如 `clip`、`lead`、`researcher`）。 |

**示例：**

```bash
librefang hand activate clip
librefang hand activate researcher
```

---

### librefang hand deactivate \<name\>

停用正在运行的 Hand，停止其执行。

```
librefang hand deactivate <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | 要停用的 Hand ID。 |

**示例：**

```bash
librefang hand deactivate clip
```

---

### librefang hand status [name]

显示指定 Hand 或所有活跃 Hand 的状态。

```
librefang hand status [<NAME>]
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | 可选的 Hand ID。如果省略，显示所有活跃 Hand。 |

**示例：**

```bash
# 显示所有活跃 Hand
librefang hand status

# 显示指定 Hand 的状态
librefang hand status clip
```

---

### librefang hand install \<path\>

从包含 `HAND.toml` 清单文件的本地目录安装 Hand。

```
librefang hand install <PATH>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<PATH>` | Hand 目录路径（必须包含 `HAND.toml`）。 |

**示例：**

```bash
librefang hand install ./my-hand
```

---

### librefang hand info \<name\>

显示 Hand 的详细信息，包括其能力、依赖和配置。

```
librefang hand info <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID。 |

**示例：**

```bash
librefang hand info clip
```

---

### librefang hand check-deps \<name\>

检查 Hand 所需的所有依赖是否已安装。

```
librefang hand check-deps <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID。 |

**示例：**

```bash
librefang hand check-deps clip
```

---

### librefang hand install-deps \<name\>

安装 Hand 所需的缺失依赖。

```
librefang hand install-deps <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID。 |

**示例：**

```bash
librefang hand install-deps clip
```

---

### librefang hand pause \<name\>

暂停正在运行的 Hand，但不完全停用。之后可以恢复运行。

```
librefang hand pause <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID 或实例 ID。 |

**示例：**

```bash
librefang hand pause clip
```

---

### librefang hand resume \<name\>

恢复先前暂停的 Hand。

```
librefang hand resume <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Hand ID 或实例 ID。 |

**示例：**

```bash
librefang hand resume clip
```

---

## 工作流命令

所有工作流命令需要守护进程正在运行。

### librefang workflow list

列出所有已注册的工作流。

```
librefang workflow list
```

**输出列：** ID、NAME、STEPS、CREATED。

---

### librefang workflow create

从 JSON 定义文件创建工作流。

```
librefang workflow create <FILE>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<FILE>` | 描述工作流步骤的 JSON 文件路径。 |

**示例：**

```bash
librefang workflow create ./my-workflow.json
```

---

### librefang workflow run

通过 ID 执行工作流。

```
librefang workflow run <WORKFLOW_ID> <INPUT>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<WORKFLOW_ID>` | 工作流 UUID。可通过 `librefang workflow list` 获取。 |
| `<INPUT>` | 传递给工作流的输入文本。 |

**示例：**

```bash
librefang workflow run abc123 "Analyze this code for security issues"
```

---

## 触发器命令

所有触发器命令需要守护进程正在运行。

### librefang trigger list

列出所有事件触发器。

```
librefang trigger list [--agent-id <ID>]
```

**选项：**

| 选项 | 说明 |
|---|---|
| `--agent-id <ID>` | 按所属 Agent 的 UUID 筛选触发器。 |

**输出列：** TRIGGER ID、AGENT ID、ENABLED、FIRES、PATTERN。

---

### librefang trigger create

为 Agent 创建事件触发器。

```
librefang trigger create <AGENT_ID> <PATTERN_JSON> [选项]
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<AGENT_ID>` | 拥有该触发器的 Agent 的 UUID。 |
| `<PATTERN_JSON>` | 触发器模式，以 JSON 字符串形式提供（如 `'"lifecycle"'`）。 |

**选项：**

| 选项 | 默认值 | 说明 |
|---|---|---|
| `--prompt <TEMPLATE>` | `"Event: {{event}}"` | 提示模板，使用 `{{event}}` 作为事件数据占位符。 |
| `--max-fires <N>` | `0`（无限制） | 触发器最大触发次数。 |
| `--target-agent <ID>` | （拥有者自身） | 将触发消息路由到另一个 Agent 而非拥有者。 |
| `--cooldown <SECS>` | 无 | 连续两次触发之间的最短间隔（秒）。 |
| `--session-mode <MODE>` | Agent 默认值 | 覆盖触发调用的会话模式（`persistent` 或 `new`）。 |

**模式示例：**

```bash
# 在任何生命周期事件时触发
librefang trigger create <AGENT_ID> '"lifecycle"'

# 在任意 Agent 生成时触发
librefang trigger create <AGENT_ID> '"agent_spawned"'

# 在 Agent 终止时触发，最多 5 次，冷却 60 秒
librefang trigger create <AGENT_ID> '"agent_terminated"' --max-fires 5 --cooldown 60

# 在所有事件时触发，消息路由给另一个 Agent
librefang trigger create <AGENT_ID> '"all"' --target-agent <OTHER_AGENT_ID>

# 自定义模式 JSON
librefang trigger create <AGENT_ID> '{"agent_spawned":{"name_pattern":"worker-*"}}'
```

---

### librefang trigger get

查看单个触发器的完整详情。

```
librefang trigger get <TRIGGER_ID>
```

---

### librefang trigger update

部分更新触发器，只修改指定的字段。

```
librefang trigger update <TRIGGER_ID> [选项]
```

**选项：**

| 选项 | 说明 |
|---|---|
| `--pattern <JSON>` | 新的事件模式（JSON 字符串）。 |
| `--prompt <TEMPLATE>` | 新的提示模板。 |
| `--enabled <true\|false>` | 启用或禁用触发器。 |
| `--max-fires <N>` | 新的最大触发次数。 |
| `--cooldown <SECS>` | 新的冷却时间（秒）。 |
| `--clear-cooldown` | 完全移除冷却限制。 |
| `--session-mode <MODE>` | 新的会话模式覆盖（`persistent` 或 `new`）。 |
| `--clear-session-mode` | 移除会话模式覆盖，恢复 Agent 默认值。 |
| `--target-agent <ID>` | 将触发消息路由到另一个 Agent（UUID）。 |
| `--clear-target-agent` | 移除目标 Agent 覆盖，恢复拥有者路由。 |

```bash
# 修改提示并设置 30 秒冷却
librefang trigger update <TRIGGER_ID> --prompt "告警：{{event}}" --cooldown 30

# 移除冷却
librefang trigger update <TRIGGER_ID> --clear-cooldown

# 切换到 new 会话模式
librefang trigger update <TRIGGER_ID> --session-mode new

# 将触发重定向到另一个 Agent
librefang trigger update <TRIGGER_ID> --target-agent <OTHER_AGENT_ID>

# 清除目标 Agent 重定向
librefang trigger update <TRIGGER_ID> --clear-target-agent
```

---

### librefang trigger enable / disable

启用或禁用触发器，不会删除它。

```
librefang trigger enable <TRIGGER_ID>
librefang trigger disable <TRIGGER_ID>
```

---

### librefang trigger delete

通过 ID 删除触发器。

```
librefang trigger delete <TRIGGER_ID>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<TRIGGER_ID>` | 要删除的触发器 UUID。 |

---

## 技能命令

### librefang skill list

列出所有已安装的技能。

```
librefang skill list
```

**输出列：** NAME、VERSION、TOOLS、DESCRIPTION。

从 `~/.librefang/skills/`（从仪表板安装或用户自定义）加载技能。

---

### librefang skill install

从本地目录、Git URL 或 FangHub 市场安装技能。

```
librefang skill install <SOURCE>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<SOURCE>` | 技能名称（FangHub）、本地目录路径或 Git URL。 |

**行为：**

- **本地目录：** 在目录中查找 `skill.toml`。如果未找到，检查 OpenClaw 格式技能（带有 YAML frontmatter 的 SKILL.md）并自动转换。
- **远程（FangHub）：** 从 FangHub 市场获取并安装。技能通过 SHA256 验证和提示注入扫描。

**示例：**

```bash
# 从本地目录安装
librefang skill install ./my-skill/

# 从 FangHub 安装
librefang skill install web-search

# 安装 OpenClaw 格式技能
librefang skill install ./openclaw-skill/
```

---

### librefang skill remove

移除已安装的技能。

```
librefang skill remove <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | 要移除的技能名称。 |

**示例：**

```bash
librefang skill remove web-search
```

---

### librefang skill search

在 FangHub 市场中搜索技能。

```
librefang skill search <QUERY>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<QUERY>` | 搜索查询字符串。 |

**示例：**

```bash
librefang skill search "docker kubernetes"
```

---

### librefang skill create

交互式创建新技能项目脚手架。

```
librefang skill create
```

**行为：**

提示输入：
- 技能名称
- 描述
- 运行时（`python`、`node` 或 `wasm`；默认为 `python`）

在 `~/.librefang/skills/<name>/` 下创建目录，包含：
- `skill.toml` -- 清单文件
- `src/main.py`（或 `src/index.js`）-- 带有样板代码的入口文件

**示例：**

```bash
librefang skill create
# Skill name: my-tool
# Description: A custom analysis tool
# Runtime (python/node/wasm) [python]: python
```

---

## 通道命令

所有通道都以独立进程的 sidecar adapter 形式运行 —— 这些命令调用
存活的 daemon endpoint（`GET /api/channels`、`GET /api/channels/registry`、
`POST /api/channels/sidecar/{name}/configure`、`POST /api/channels/reload`），
而不是直接操作进程内 adapter 状态。

### librefang channel list

通过 `GET /api/channels` 列出已配置 + 可发现的通道。

```
librefang channel list
```

**列：** NAME、KIND、CONFIGURED、TOKEN（必需的 secret 环境变量是否已设值）、24H MSGS。

需要 daemon 在跑 —— 不通就报错退出。要不连 daemon 看配置，直接读
`~/.librefang/config.toml`。

---

### librefang channel reload

调 `POST /api/channels/reload`，让 daemon 从 `~/.librefang/config.toml`
（包括 `include` 的所有文件）重读 `[[sidecar_channels]]`，不重启。
适用于：手动改完配置后，或 `librefang channel rm` 之后。

```
librefang channel reload
```

---

### librefang channel setup

按 sidecar 自描述 schema 走的交互式配置。

```
librefang channel setup [<NAME>]
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | Sidecar adapter 名字（`telegram`、`ntfy` 等）。省略则在未配置项里弹 picker。 |

按 sidecar 的 `--describe` schema 逐字段询问：

- **非 secret 字段有当前值**会预填；空提交保留当前值。
- **secret 类型字段且 `has_value=true`** 永远不回显 —— 显示成
  `(set — leave blank to keep)`。空提交保留已存 secret。
- **必填字段**在提示里加 `*`。

提交时 POST 到 `/api/channels/sidecar/{name}/configure`，daemon 把
secret 类字段写到 `~/.librefang/secrets.env`、其他写到 `config.toml`
的 `[[sidecar_channels]]` 里，然后热加载。

**示例：**

```bash
# 在未配置 adapter 里弹交互式选择器
librefang channel setup

# 直接对一个 adapter 走配置流
librefang channel setup telegram
```

---

### librefang channel rm

从 `~/.librefang/config.toml` 里删掉匹配的 `[[sidecar_channels]]` 条目，
然后热加载让对应 sidecar 子进程退出。

```
librefang channel rm <NAME>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<NAME>` | 要删除的 sidecar 条目的 `name` 字段。 |

Sidecar 迁移后，`[[sidecar_channels]]` 块是否存在就是唯一的开关
信号（#5463 之前的 `enable` / `disable` 没有恢复），所以 `rm` 是
关闭 adapter 的唯一方式。

**示例：**

```bash
librefang channel rm telegram
```

---

### 没有恢复的子命令

`librefang channel test` / `enable` / `disable` **故意不**从
#5463 之前的形态恢复：

- **`test`** —— sidecar 用自己的 stdout 日志暴露健康状态；没有
  in-band 的 `/test` endpoint。改 tail `librefang logs --filter
  sidecar/<name>`。
- **`enable` / `disable`** —— sidecar 是否启动取决于 `config.toml` 里
  有没有它的 `[[sidecar_channels]]` 块。`rm` 是关；`setup`（或手动改
  完 `reload`）是开。

---

## 配置命令

### librefang config show

显示当前配置文件内容。

```
librefang config show
```

以文件路径作为头部注释，打印 `~/.librefang/config.toml` 的内容。

---

### librefang config edit

在编辑器中打开配置文件。

```
librefang config edit
```

优先使用 `$EDITOR`，然后 `$VISUAL`，回退到 `notepad`（Windows）或 `vi`（Unix）。

---

### librefang config get

通过点分隔键路径获取单个配置值。

```
librefang config get <KEY>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<KEY>` | TOML 结构中的点分隔键路径。 |

**示例：**

```bash
librefang config get default_model.provider
# groq

librefang config get api_listen
# 127.0.0.1:4545

librefang config get memory.decay_rate
# 0.05
```

---

### librefang config set

通过点分隔键路径设置配置值。

```
librefang config set <KEY> <VALUE>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<KEY>` | 点分隔键路径。 |
| `<VALUE>` | 新值。类型根据现有值推断（整数、浮点数、布尔值或字符串）。 |

**注意：** 此命令会重新序列化 TOML 文件，所有注释将被删除。

**示例：**

```bash
librefang config set default_model.provider anthropic
librefang config set default_model.model claude-sonnet-4-20250514
librefang config set api_listen "0.0.0.0:4545"
```

---

### librefang config set-key

将 LLM 提供商 API 密钥保存到 `~/.librefang/.env`。

```
librefang config set-key <PROVIDER>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<PROVIDER>` | 提供商名称（如 `groq`、`anthropic`、`openai`、`gemini`、`deepseek`、`openrouter`、`together`、`mistral`、`fireworks`、`perplexity`、`cohere`、`xai`、`brave`、`tavily`）。 |

**行为：**

- 交互式提示输入 API 密钥。
- 以 `<PROVIDER_NAME>_API_KEY=<value>` 格式保存到 `~/.librefang/.env`。
- 对提供商 API 执行在线验证测试。
- 在 Unix 上，文件权限限制为仅所有者访问。

**示例：**

```bash
librefang config set-key groq
# Paste your groq API key: gsk_...
# [ok] Saved GROQ_API_KEY to ~/.librefang/.env
# Testing key... OK
```

---

### librefang config delete-key

从 `~/.librefang/.env` 中删除 API 密钥。

```
librefang config delete-key <PROVIDER>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<PROVIDER>` | 提供商名称。 |

**示例：**

```bash
librefang config delete-key openai
```

---

### librefang config unset

从 `config.toml` 中删除一个**配置 key**(和 `delete-key` 不同 —— 后者删 `.env` 里的 provider API key)。

```
librefang config unset <KEY>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<KEY>` | 要删的配置点路径(如 `api.cors_origin`、`triggers.cooldown_secs`)。 |

**示例：**

```bash
librefang config unset api.cors_origin
```

> **注意:** `unset` 会重写 TOML 文件并**抹掉注释**。如果你在 `config.toml` 里维护了手写注释,改用手动编辑。

---

### librefang config test-key

使用已存储的 API 密钥测试提供商连接。

```
librefang config test-key <PROVIDER>
```

**参数：**

| 参数 | 说明 |
|---|---|
| `<PROVIDER>` | 提供商名称。 |

**行为：**

- 从环境中读取 API 密钥（从 `~/.librefang/.env` 加载）。
- 请求提供商的模型/健康检查端点。
- 报告 `OK`（密钥已接受）或 `FAILED (401/403)`（密钥被拒绝）。
- 失败时以退出码 1 退出。

**示例：**

```bash
librefang config test-key groq
# Testing groq (GROQ_API_KEY)... OK
```

---

## 服务管理命令

管理系统启动服务，使 LibreFang 在登录或重启时自动启动。

### librefang service install

注册平台特定的自启动服务。

```
librefang service install
```

**行为：**

- **Linux：** 在 `~/.config/systemd/user/librefang.service` 创建 systemd 用户服务，然后执行 `systemctl --user daemon-reload` 和 `systemctl --user enable librefang.service`。
- **macOS：** 在 `~/Library/LaunchAgents/ai.librefang.daemon.plist` 创建 LaunchAgent，并通过 `launchctl load` 加载。
- **Windows：** 在 `HKCU\Software\Microsoft\Windows\CurrentVersion\Run` 添加 `LibreFang` 注册表项。

二进制路径通过当前运行的可执行文件自动检测。如果移动了二进制文件，重新运行 `librefang service install` 即可更新路径。

**示例：**

```bash
librefang service install
# ✓ Wrote /home/user/.config/systemd/user/librefang.service
# ✓ Service enabled (will start on next login)
```

对于无图形界面的 Linux 服务器（无登录会话），还需要启用 lingering 以便用户服务在开机时启动：

```bash
loginctl enable-linger
```

---

### librefang service uninstall

移除已安装的自启动服务。

```
librefang service uninstall
```

**行为：**

- **Linux：** 禁用并移除 systemd 用户服务，然后重新加载守护进程。
- **macOS：** 卸载并移除 LaunchAgent plist 文件。
- **Windows：** 删除注册表 Run 项。

**示例：**

```bash
librefang service uninstall
# ✓ Removed systemd user service
```

---

### librefang service status

检查自启动服务是否已注册并正在运行。

```
librefang service status
```

**示例：**

```bash
librefang service status
# ✓ Systemd user service is registered
#   Enabled: enabled
#   Active: active
```

---

## 聊天里的 Slash Command

交互式聊天（`librefang chat`、`librefang agent chat`、TUI 聊天面板）接受 slash command。所有命令来自一个跟 channel adapter（Telegram、Slack 等）和 dashboard 共享的注册中心，所以同一个命令名在每个表面含义一致。

聊天会话里输入 `/help` 渲染按 CLI 视角过滤后的命令列表：

```
/model [name] — 显示或切换 agent 模型
/status       — 显示系统状态
/help         — 显示本帮助
/clear        — 清空聊天历史
/kill         — 杀掉当前 agent 并退出
/exit         — 结束聊天会话
```

| 命令 | 说明 |
|---|---|
| `/model [name]` | 显示当前模型，或切换到 `<name>`（带 provider 前缀，如 `groq/llama-3.3-70b-versatile`）。 |
| `/status` | 打印连接和 agent 状态。 |
| `/help` | 打印 CLI 命令列表。 |
| `/clear` | 清空可见聊天历史，不重置 session。 |
| `/kill` | 终止当前 agent 并退出聊天。 |
| `/exit` | 结束聊天会话。`quit` 是别名。 |

channel adapter 暴露的命令（`/agents`、`/new`、`/usage`、`/triggers`、`/budget` 等）见 [Provider 管理 — Channel 命令](/zh/configuration/providers/management)。注意 **`/new` 是分叉出新会话，不是清空当前会话** — 旧会话保留在通道里仍可恢复。未知命令名只会得到一个 "unknown command" 错误，不会被传给模型。

---

## 顶层命令参考

在上面 agent / hand / skill / workflow / channel / config 几组之外,这些顶层命令也随 CLI 一起发布。所有命令都对照过 `crates/librefang-cli/src/main.rs` 验证为真;部分是嵌套形式的别名。

### Daemon 生命周期

| 命令 | 用途 | 主要 flag |
|---|---|---|
| `librefang start` | 启动 daemon。 | `--foreground`(不 fork)、`--log-file <path>` |
| `librefang stop` | 停止运行中的 daemon。 | — |
| `librefang restart` | 重启 daemon。 | `--tail`(跟新日志)、`--foreground` |
| `librefang health` | 快速就绪探针。 | `--json` |
| `librefang status` | 显示 kernel 与 provider 状态。 | `--watch <secs>`(刷新循环) |
| `librefang logs` | tail daemon 日志。 | `--lines <n>`、`--follow` / `-f` |
| `librefang tui` | 启动交互终端 dashboard。 | — |

### 安装 / 引导 / 迁移

| 命令 | 用途 | 备注 |
|---|---|---|
| `librefang onboard` | 交互式安装向导。 | `--quick`、`--upgrade` |
| `librefang setup` | 非交互式 `init --quick` 别名。 | `--quick`、`--upgrade` |
| `librefang configure` | 凭据与 channel 交互配置向导。 | — |
| `librefang migrate --from <framework>` | 从其他框架导入配置/会话。 | `<framework>` 取值 `openclaw`、`langchain`、`autogpt`、`openfang` |
| `librefang reset --confirm` | 抹除本地配置和状态(破坏性)。 | 需要 `--confirm` |
| `librefang uninstall` | 卸载 LibreFang。 | `--confirm`、`--keep-config` |

### 目录与注册表

| 命令 | 用途 | 子命令 |
|---|---|---|
| `librefang models` | LLM 模型目录。 | `list`、`aliases`、`providers`、`set` |
| `librefang mcp` | MCP server 管理。 | `list`、`catalog`、`add`、`remove` |
| `librefang webhooks` | 出站 webhook 管理。 | `list`、`create`、`test`、`delete` |
| `librefang sessions [agent]` | 列出对话 session。 | `--json` |
| `librefang memory` | Agent memory KV 存储。 | `list`、`get`、`set`、`delete` |
| `librefang cron` | 定时任务管理。 | `list`、`create`、`delete`、`enable`、`disable` |
| `librefang approvals` | Approval 队列。 | `list`、`approve`、`reject` |

### 安全 / 认证 / 凭据库

| 命令 | 用途 | 子命令 |
|---|---|---|
| `librefang vault` | 加密凭据库。 | `init`、`set`、`list`、`remove` |
| `librefang auth chatgpt` | ChatGPT 认证(浏览器 OAuth)。 | `--device-auth` |
| `librefang security` | 安全审计与验证。 | `status`、`audit`、`verify` |
| `librefang devices` | 设备配对管理。 | `list`、`pair`、`remove` |
| `librefang qr` | 在 stdout 渲染配对二维码。 | — |
| `librefang hash-password` | 给 `dashboard_pass_hash` 生成 Argon2id 哈希。 | `--password <plain>`(否则交互输入) |

### Agent 简写(嵌套形式的别名)

| 命令 | 等同于 | 用途 |
|---|---|---|
| `librefang spawn <template>` | `agent spawn` | 从模板/manifest spawn agent。`--name`、`--dry-run` |
| `librefang agents` | `agent list` | 列出 agent。`--json` |
| `librefang kill <agent_id>` | `agent kill` | 杀掉运行中的 agent。 |
| `librefang message <agent> <text>` | — | 发一次性消息,打印回复。`--json` |

### 脚手架

| 命令 | 用途 |
|---|---|
| `librefang new skill` | 脚手架一个新 skill(交互式)。 |
| `librefang new mcp` | 脚手架一个新 MCP server。 |

### `librefang hand` 额外子命令

hand 组已经有上面文档里的 `list / install / activate / info / check-deps / install-deps / pause / resume / deactivate`。下面这些是补充的:

| 子命令 | 用途 |
|---|---|
| `hand status [id]` | 显示 hand 状态(单个或全部)。 |
| `hand active` | 列出活跃 hand 实例。 |
| `hand settings <name>` | 显示某 hand 当前配置。 |
| `hand set <name> <key> <value>` | 设置单个 hand-config 值。 |
| `hand reload` | 从磁盘重载所有 `HAND.toml`。 |
| `hand chat <name>` | 与某活跃 hand 交互聊天。 |

### 系统与元

| 命令 | 用途 |
|---|---|
| `librefang system info` | 打印平台/版本/依赖信息。 |
| `librefang system version` | 只打印版本字符串。 |
| `librefang gateway` | 底层 daemon 控制(start / stop / restart / status), 给绕过友好 `start` 包装的 service 监督进程用。 |

### 上面没列出的 Slash 命令

这些 slash 命令在 registry 里跟 `/help` / `/clear` 等并存,但之前没文档化:

| 命令 | 行为 |
|---|---|
| `/reboot` | 重启 agent 进程(重置进程内状态,但保留 session 历史)。 |
| `/compact` | 在当前 session 上触发一轮 LLM 摘要。 |
| `/think` | 切换下一回复时的 chain-of-thought / 推理过程是否可见。 |

channel adapter 暴露的命令（`/agents`、`/new`、`/usage`、`/triggers`、`/budget` 等）见 [Provider 管理 — Channel 命令](/zh/configuration/providers/management)。注意 **`/new` 是分叉出新会话，不是清空当前会话** — 旧会话保留在通道里仍可恢复。未知命令名只会得到一个 "unknown command" 错误，不会被传给模型。
