CLI 命令参考

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

有关 CLI 概述、安装说明和全局选项，请参阅 CLI 参考。有关使用示例和指南，请参阅 CLI 示例与指南。

Agent 命令

librefang agent new

从内置模板生成 Agent。

librefang agent new [<TEMPLATE>]

参数：

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

行为：

模板来自三个来源，按优先级从高到低：LIBREFANG_AGENTS_DIR（环境变量覆盖）、~/.librefang/agent-types/<name>.toml（仪表板编辑器与 agent_type_create 写入的规范存储）、以及 ~/.librefang/workspaces/agents/（assistant 为预装，其余由仪表板安装）。前两者与守护进程自身解析模板的顺序一致；该环境变量只是 CLI 侧的覆盖，守护进程从不读取它。
模板要么是 agent-types/ 中的扁平 <name>.toml，要么是另外两个来源中包含 agent.toml 清单的目录。
守护进程模式下：发送 POST /api/agents 请求附带清单内容。Agent 将被持久化。
独立模式下：启动进程内核。Agent 是临时的。

示例：

# 交互式选择器
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。

示例：

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（进程内模式）。

示例：

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 结束会话。

示例：

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

librefang agent kill

终止正在运行的 Agent。

librefang agent kill <AGENT_ID>

参数：

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

示例：

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

librefang message

向 Agent 发送一条消息并打印回复。与 agent chat 不同，这是单次请求，适用于脚本和自动化。

librefang message <AGENT> <TEXT> [--json] [--incognito] [--session-id <UUID>]

参数：

参数	说明
`<AGENT>`	Agent 名称或 UUID。
`<TEXT>`	要发送的消息。

选项：

选项	默认值	说明
`--json`	关闭	打印原始 JSON 响应，而不仅是回复文本。
`--incognito`	关闭	本轮不写入会话与记忆；记忆读取仍然生效。
`--session-id <UUID>`	（规范会话）	指定要对话的具体会话。也可写作 `--session`。

会话定向：

不传 --session-id 时，守护进程解析到该 Agent 的规范会话——每个 Agent 只有一个对话。这对个人 Agent 没有问题，但对同时服务多个互不相关的用户的 Agent 就是错的：所有调用者的对话都落在同一段历史里，于是每位访客的文本都会出现在下一位访客那一轮的模型上下文中，而这段共享记录会在每一轮被重新发送并计费，直到撞上上下文上限。

传入按对话区分的 UUID，每个对话就拥有各自的历史。相同的 UUID 继续同一个对话，不同的 UUID 开启一个隔离的对话。这与 POST /api/agents/{id}/message 的 session_id 字段等价。

--incognito 不能替代它：它会完全抑制会话写入，因此单个对话内部的连续性也会丢失。

与 session_mode 的关系：

显式的 --session-id 位于内核会话解析阶梯的最顶端，因此在两个方向上都优先于 agent.toml 中的 session_mode：

`session_mode`	不传 `--session-id`	传 `--session-id`
`persistent`（默认）	每次调用都复用该 Agent 唯一的规范会话。	改用指定的会话；规范会话不受影响。
`new`	每次调用都新建一个一次性会话。	指定的会话会在多次调用间复用，从而为该对话恢复连续性。

会话必须属于被寻址的 Agent。属于其他 Agent 的 UUID 会被拒绝而不会被读取，因此一个 Agent 的 id 永远无法暴露另一个 Agent 的历史。格式非法的 UUID 会在发出请求之前由 CLI 拒绝。

示例：

# 规范会话——行为与以往一致
librefang message coder "Fix the bug in main.rs"

# 与同一个 Agent 的两个隔离对话
librefang message sales "My customer code is PINE-77." --session-id 11111111-1111-4111-8111-111111111111
librefang message sales "What is my customer code?"    --session-id 22222222-2222-4222-8222-222222222222

# 继续第一个对话
librefang message sales "And how many licences does that cover?" --session-id 11111111-1111-4111-8111-111111111111

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`）。

示例：

librefang hand activate clip
librefang hand activate researcher

librefang hand deactivate <name>

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

librefang hand deactivate <NAME>

参数：

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

示例：

librefang hand deactivate clip

librefang hand status [name]

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

librefang hand status [<NAME>]

参数：

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

示例：

# 显示所有活跃 Hand
librefang hand status

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

librefang hand install <path>

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

librefang hand install <PATH>

参数：

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

示例：

librefang hand install ./my-hand

librefang hand info <name>

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

librefang hand info <NAME>

参数：

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

示例：

librefang hand info clip

librefang hand check-deps <name>

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

librefang hand check-deps <NAME>

参数：

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

示例：

librefang hand check-deps clip

librefang hand install-deps <name>

安装 Hand 所需的缺失依赖。

librefang hand install-deps <NAME>

参数：

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

示例：

librefang hand install-deps clip

librefang hand pause <name>

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

librefang hand pause <NAME>

参数：

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

示例：

librefang hand pause clip

librefang hand resume <name>

恢复先前暂停的 Hand。

librefang hand resume <NAME>

参数：

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

示例：

librefang hand resume clip

工作流命令

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

librefang workflow list

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

librefang workflow list

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

librefang workflow create

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

librefang workflow create <FILE>

参数：

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

示例：

librefang workflow create ./my-workflow.json

librefang workflow run

通过 ID 执行工作流。

librefang workflow run <WORKFLOW_ID> <INPUT>

参数：

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

示例：

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`）。

模式示例：

# 在任何生命周期事件时触发
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 覆盖，恢复拥有者路由。

# 修改提示并设置 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 验证和提示注入扫描。

示例：

# 从本地目录安装
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>`	要移除的技能名称。

示例：

librefang skill remove web-search

librefang skill search

在 FangHub 市场中搜索技能。

librefang skill search <QUERY>

参数：

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

示例：

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）-- 带有样板代码的入口文件

示例：

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]] 里，然后热加载。

示例：

# 在未配置 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 的唯一方式。

示例：

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 结构中的点分隔键路径。

示例：

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 文件，所有注释将被删除。

示例：

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 上，文件权限限制为仅所有者访问。

示例：

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>`	提供商名称。

示例：

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`)。

示例：

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 退出。

示例：

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 即可更新路径。

示例：

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

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

loginctl enable-linger

`--system`（macOS）：开机启动，而非登录后启动

上述三个平台的默认行为注册的都是用户级服务，只有该用户登录后才会启动。因此一台重启后停在登录界面（或 FileVault 解锁界面）的 Mac 并不会启动守护进程——这对需要常驻运行的部署是个实际问题。

--system 改为将 LaunchDaemon 写入 /Library/LaunchDaemons/ai.librefang.daemon.plist。 launchd 会在开机时、任何用户登录之前加载该目录。

sudo librefang service install --system

它需要 root 权限，并且必须通过 sudo 调用，而不能直接以 root 身份登录后执行：守护进程需要以一个真实账户运行，而 SUDO_USER 是唯一能标识该账户的信息。生成的 job 会把 UserName 设为你的账户，HOME 指向你的主目录，LIBREFANG_HOME 指向 ~/.librefang，并在安装时把该状态目录及其中的 daemon.log 的所有权移交给你——launchd 会在降权之前打开日志文件，若不做这一步，守护进程将无法写入自己的日志。

移除时使用同一个 flag：

sudo librefang service uninstall --system

librefang service status 会同时报告用户级 LaunchAgent 和开机启动的 LaunchDaemon，无需任何 flag。

--system 仅适用于 macOS。在 NixOS 上请使用 services.librefang 模块；其他 Linux 发行版可将系统级 unit 写入 /etc/systemd/system/，或继续使用用户级服务加 loginctl enable-linger。

librefang service uninstall

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

librefang service uninstall

行为：

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

示例：

librefang service uninstall
# ✓ Removed systemd user service

librefang service status

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

librefang service status

示例：

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 命令。注意 /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`	存活探针；daemon 报告子系统异常时退出码为 1。	`--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`、`connect`
`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`、`--incognito`、`--session-id <UUID>` — 见 librefang message。

脚手架

命令	用途
`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 / 推理过程是否可见。

CLI 命令参考

librefang agent new

librefang agent spawn

librefang agent list

librefang agent chat

librefang agent kill

librefang message

librefang hand list

librefang hand active

librefang hand activate <name>

librefang hand deactivate <name>

librefang hand status [name]

librefang hand install <path>

librefang hand info <name>

librefang hand check-deps <name>

librefang hand install-deps <name>

librefang hand pause <name>

librefang hand resume <name>

librefang workflow list

librefang workflow create

librefang workflow run

librefang trigger list

librefang trigger create

librefang trigger get

librefang trigger update

librefang trigger enable / disable

librefang trigger delete

librefang skill list

librefang skill install

librefang skill remove

librefang skill search

librefang skill create

librefang channel list

librefang channel reload

librefang channel setup

librefang channel rm

没有恢复的子命令

librefang config show

librefang config edit

librefang config get

librefang config set

librefang config set-key

librefang config delete-key

librefang config unset

librefang config test-key

librefang service install

--system（macOS）：开机启动，而非登录后启动

librefang service uninstall

librefang service status

Daemon 生命周期

安装 / 引导 / 迁移

目录与注册表

安全 / 认证 / 凭据库

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

脚手架

librefang hand 额外子命令

系统与元

上面没列出的 Slash 命令

`--system`（macOS）：开机启动，而非登录后启动

`librefang hand` 额外子命令