LibreFang CLI 参考

子页面： 命令参考 | 示例与指南

librefang 命令行工具的完整参考，用于管理 LibreFang Agent OS。

概述

librefang 二进制是管理 LibreFang Agent OS 的主要接口。支持两种操作模式：

• 守护进程模式 -- 当守护进程运行时（librefang start），CLI 命令通过 HTTP 与其通信。推荐在生产环境中使用此模式。
• 进程内模式 -- 未检测到守护进程时，支持此模式的命令将启动临时进程内核。在此模式下生成的 Agent 不会持久化，进程退出后即丢失。

不带子命令运行 librefang 将启动基于 ratatui 构建的交互式 TUI（终端用户界面），在终端中提供完整的仪表板体验。

安装

从源码 (cargo)

cargo install --path crates/librefang-cli

从工作空间构建

cargo build --release -p librefang-cli
# 二进制文件: target/release/librefang (Windows 上为 librefang.exe)

Docker

docker run -it librefang/librefang:latest

Homebrew (macOS)

brew tap librefang/tap
brew install librefang              # CLI (stable)
brew install --cask librefang       # Desktop (stable)
# Beta/RC 频道:
# brew install librefang-beta       # or librefang-rc
# brew install --cask librefang-rc  # or librefang-beta

Shell 安装脚本

curl -fsSL https://get.librefang.ai | sh

全局选项

以下选项适用于所有命令。

环境变量：

命令参考

librefang（无子命令）

启动交互式 TUI 仪表板。

librefang [--config <PATH>]

TUI 提供全屏终端界面，包含 Agent、聊天、工作流、通道、技能、设置等面板。追踪输出重定向到 ~/.librefang/tui.log，以避免破坏终端显示。

按 Ctrl+C 退出。再次按 Ctrl+C 强制退出进程。

librefang init

初始化 LibreFang 工作空间。创建 ~/.librefang/ 目录，包含子目录（data/、workspaces/agents/）和默认的 config.toml。

librefang init [--quick]

选项：

行为：

• 不带 --quick：启动交互式五步引导向导（ratatui TUI），引导完成提供商选择、API 密钥配置，并可选择启动守护进程。
• 带 --quick：按优先级检查环境变量自动检测提供商：Groq、Gemini、DeepSeek、Anthropic、OpenAI、OpenRouter。如果未找到任何提供商，回退到 Groq。
• 在 Unix 系统上，文件权限限制为仅所有者访问（文件 0600，目录 0700）。

示例：

# 交互式设置
librefang init

# 非交互式（CI/脚本）
export GROQ_API_KEY="gsk_..."
librefang init --quick

librefang start

启动 LibreFang 守护进程（内核 + API 服务器）。

librefang start [--config <PATH>]

行为：

• 如果 ~/.librefang/ 中不存在 config.toml，首次运行 start 命令时会自动执行快速初始化向导。
• 检查是否已有守护进程在运行；如果有，则报错退出。
• 启动 LibreFang 内核（加载配置、初始化 SQLite 数据库、加载 Agent、连接 MCP 服务器、启动后台任务）。
• 在 config.toml 指定的地址启动 HTTP API 服务器（默认：127.0.0.1:4545）。
• 将 daemon.json 写入 ~/.librefang/，以便其他 CLI 命令发现正在运行的守护进程。
• 阻塞运行，直到通过 Ctrl+C 中断。

输出：

  LibreFang Agent OS v0.7.0

  Starting daemon...

  [ok] Kernel booted (groq/llama-3.3-70b-versatile)
  [ok] 50 models available
  [ok] 3 agent(s) loaded

  API:        http://127.0.0.1:4545
  Dashboard:  http://127.0.0.1:4545/
  Provider:   groq
  Model:      llama-3.3-70b-versatile

  hint: Open the dashboard in your browser, or run `librefang chat`
  hint: Press Ctrl+C to stop the daemon

示例：

# 使用默认配置启动
librefang start

# 使用自定义配置启动
librefang start --config /path/to/config.toml

librefang status

显示当前内核/守护进程状态。

librefang status [--json]

选项：

行为：

• 如果守护进程正在运行：查询 GET /api/status，显示 Agent 数量、提供商、模型、运行时间、API 地址、数据目录以及活跃 Agent 列表。
• 如果没有守护进程运行：启动进程内核并显示持久化状态。显示守护进程未运行的警告。

示例：

librefang status

librefang status --json | jq '.agent_count'

librefang doctor

对 LibreFang 安装进行诊断检查。

librefang doctor [--json] [--repair]

选项：

执行的检查项：

1. LibreFang 目录 -- ~/.librefang/ 是否存在
2. .env 文件 -- 是否存在且权限正确（Unix 上为 0600）
3. 配置 TOML 语法 -- config.toml 能否正确解析
4. 守护进程状态 -- 守护进程是否正在运行
5. 端口 4545 可用性 -- 如果守护进程未运行，检查端口是否空闲
6. 过期的 daemon.json -- 崩溃后残留的 daemon.json
7. 数据库文件 -- SQLite 魔术字节验证
8. 磁盘空间 -- 可用空间不足 100MB 时发出警告（仅 Unix）
9. Agent 清单文件 -- 验证 ~/.librefang/workspaces/agents/ 中所有 .toml 文件
10. LLM 提供商密钥 -- 检查 10 个提供商的环境变量（Groq、OpenRouter、Anthropic、OpenAI、DeepSeek、Gemini、Google、Together、Mistral、Fireworks），执行在线验证（401/403 检测）
11. 通道令牌 -- Telegram、Discord、Slack 令牌的格式验证
12. 配置一致性 -- 检查配置中 api_key_env 引用是否与实际环境变量匹配
13. Rust 工具链 -- rustc --version

示例：

librefang doctor

librefang doctor --repair

librefang doctor --json

librefang update

将 CLI 二进制文件更新到所配置更新频道的最新版本。

librefang update [--check] [--version <TAG>] [--channel <CHANNEL>]

选项：

更新频道：

LibreFang 支持 Apple 风格的更新频道。在 config.toml 中设置默认频道：

update_channel = "stable"   # stable | beta | rc

示例：

librefang update                    # 安装当前频道的最新版本
librefang update --check            # 仅检查更新
librefang update --channel rc       # 本次使用 rc 频道
librefang update --version v0.7.0   # 安装指定版本

librefang dashboard

在默认浏览器中打开 Web 仪表板。

librefang dashboard

行为：

• 需要守护进程正在运行。
• 在系统浏览器中打开守护进程 URL（如 http://127.0.0.1:4545/）。
• 将 URL 复制到系统剪贴板（Windows 使用 PowerShell，macOS 使用 pbcopy，Linux 使用 xclip/xsel）。

示例：

librefang dashboard

librefang completion

生成 Shell 补全脚本。

librefang completion <SHELL>

参数：

示例：

# Bash
librefang completion bash > ~/.bash_completion.d/librefang

# Zsh
librefang completion zsh > ~/.zfunc/_librefang

# Fish
librefang completion fish > ~/.config/fish/completions/librefang.fish

# PowerShell
librefang completion powershell > librefang.ps1

有关 Agent、Hand、工作流、触发器、技能、通道和配置的详细命令参考，请参阅 CLI 命令参考。

快速聊天

librefang chat

快速启动聊天会话的别名。

librefang chat [<AGENT>]

参数：

行为：

• 如果 ~/.librefang/ 中不存在 config.toml，首次运行 chat 命令时会自动执行快速初始化向导。
• 守护进程模式： 在运行中的 Agent 中按名称或 ID 查找。如果未指定 Agent 名称，使用第一个可用的 Agent。如果没有 Agent 存在，建议运行 librefang agent new。
• 独立模式（无守护进程）： 启动进程内核并从模板自动生成 Agent。搜索与给定名称匹配的 Agent，然后回退到 assistant，再回退到第一个可用模板。

这是开始聊天最简单的方式 -- 无论是否有守护进程都可使用。

示例：

# 与默认 Agent 聊天
librefang chat

# 按名称与指定 Agent 聊天
librefang chat coder

# 按 UUID 与指定 Agent 聊天
librefang chat a1b2c3d4-e5f6-7890-abcd-ef1234567890

守护进程自动检测

CLI 使用两步机制检测运行中的守护进程：

1. 读取 daemon.json： 守护进程启动时将 ~/.librefang/daemon.json 写入，其中包含监听地址（如 127.0.0.1:4545）。CLI 读取此文件以获取守护进程位置。

2. 健康检查： CLI 以 2 秒超时向 GET http://<listen_addr>/api/health 发送请求。如果健康检查成功，则认为守护进程正在运行，CLI 通过 HTTP 与其通信。

如果任一步骤失败（无 daemon.json、过期文件、健康检查超时），CLI 对支持此模式的命令回退到进程内模式。需要守护进程的命令（工作流、触发器、通道测试/启用/禁用、仪表板）将报错退出并提供帮助信息。

守护进程生命周期：

librefang start          # 启动守护进程，写入 daemon.json
                        # 其他 CLI 实例检测到 daemon.json
librefang status         # 通过 HTTP 连接到守护进程
Ctrl+C                  # 守护进程关闭，daemon.json 被删除

librefang doctor --repair  # 清理崩溃后残留的 daemon.json

环境文件

LibreFang 在每次 CLI 调用时将 ~/.librefang/.env 加载到进程环境中。系统环境变量优先于 .env 中的值。

.env 文件存储 API 密钥和秘钥：

GROQ_API_KEY=gsk_...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...

建议使用 config set-key / config delete-key 命令管理密钥，而不是直接编辑文件，因为这些命令会确保正确的文件权限。

退出码

有关使用示例、迁移指南和 MCP 集成说明，请参阅 CLI 示例与指南。

支持的 LLM 提供商

以下提供商可通过 librefang config set-key 和 librefang doctor 识别：

其他搜索/获取类提供商密钥：BRAVE_API_KEY、TAVILY_API_KEY。