LibreFang 快速上手

本指南将带你安装 LibreFang、配置第一个 LLM 供应商、生成 Agent 并与其对话。

安装

CLI

CLI 是管理 Agent、Hand、工作流等核心命令行工具。

快速安装脚本（推荐）

Linux / macOS / WSL：

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

Windows (PowerShell)：

irm https://librefang.ai/install.ps1 | iex

脚本会自动识别平台与架构，下载二进制、校验 SHA256、配置 PATH，随后运行 librefang init 并启动守护进程。

环境变量：

LIBREFANG_INSTALL_DIR — 安装目录（默认：~/.librefang/bin）
LIBREFANG_VERSION — 指定版本（默认：最新版）
LIBREFANG_AUTO_START — 自动启动守护进程（默认：1）

Windows EXE（手动安装）

如果你偏好手动安装，或脚本在你的环境中无法运行：

从 GitHub Releases 下载 librefang-x86_64-pc-windows-msvc.zip（ARM 架构用 aarch64）
解压 librefang.exe 到一个目录，比如 C:\Users\<you>\.librefang\bin\
将该目录加入系统 PATH：
- 设置 → 系统 → 关于 → 高级系统设置 → 环境变量
- 在"用户变量"的 Path 上点击编辑 → 添加目录路径
打开新的终端并运行：

# 初始化配置
librefang init

# 启动守护进程
librefang start

# 在浏览器中打开 Dashboard：http://127.0.0.1:4545/
# 与默认 Agent 对话
librefang chat

librefang init 会通过配置向导生成 ~/.librefang/config.toml。必须先执行 init 再执行 start —— 否则守护进程没有配置。首次运行时，若未执行过 init，start 与 chat 会自动触发初始化。

Homebrew (macOS / Linux)

brew tap librefang/tap
brew install librefang              # 稳定版
brew install librefang-beta         # Beta
brew install librefang-rc           # RC

npm

npm install -g @librefang/cli                  # 稳定版
npm install -g @librefang/cli@next             # 最新预发布版（Beta 或 RC）
npm install -g @librefang/cli@2026.3.25-rc1    # 指定版本

pip

pip install librefang-cli                      # 稳定版
pip install librefang-cli --pre                # 最新预发布版

Cargo

cargo install --git https://github.com/librefang/librefang librefang-cli

或从源码构建（需要 just）：

git clone https://github.com/librefang/librefang.git
cd librefang
just install

Docker

docker run -d \
  --name librefang \
  -p 4545:4545 \
  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
  -v librefang-data:/data \
  ghcr.io/librefang/librefang:latest

Docker Compose：

git clone https://github.com/librefang/librefang.git
cd librefang/deploy
docker compose up -d

验证安装

librefang --version

SDK

用于将 LibreFang API 集成到你自己应用中的 SDK。

JavaScript / TypeScript

npm install @librefang/sdk                     # 稳定版
npm install @librefang/sdk@next                # 最新预发布版（Beta 或 RC）
npm install @librefang/sdk@2026.3.25-rc1       # 指定版本

Python

pip install librefang-sdk                      # 稳定版
pip install librefang-sdk --pre                # 最新预发布版（Beta 或 RC）
pip install librefang-sdk==2026.3.25rc1        # 指定版本（遵循 PEP 440）

Rust

cargo add librefang

go get github.com/librefang/librefang/sdk/go

桌面应用

基于 Tauri 2.0 的原生桌面应用。详见桌面端。

Homebrew Cask

brew tap librefang/tap
brew install --cask librefang       # 稳定版
brew install --cask librefang-beta  # Beta
brew install --cask librefang-rc    # RC

直接下载

从 GitHub Releases 下载：

macOS：.dmg（Universal）
Windows：.msi
Linux：.appimage / .deb

一键云部署

访问 deploy.librefang.ai 查看全部云部署方式。

Fly.io

curl -sL https://raw.githubusercontent.com/librefang/librefang/main/deploy/fly/deploy.sh | bash

Railway

Render

GCP（Terraform）

部署到 GCP 永久免费额度（e2-micro）。详见 deploy/gcp/README.md：

cd deploy/gcp
cp terraform.tfvars.example terraform.tfvars
# 编辑 terraform.tfvars，填入 project_id 和 API keys
terraform init && terraform apply

Linux systemd

sudo cp deploy/librefang.service /etc/systemd/system/
sudo systemctl enable --now librefang

配置

初始化

首次执行 librefang start（或通过安装脚本/Docker 入口）时会自动初始化。也可以手动运行交互式配置向导：

librefang init

这会创建 ~/.librefang/ 目录（可通过 LIBREFANG_HOME 自定义）：

~/.librefang/
├── config.toml                # 主配置文件
├── aliases.toml               # 模型和命令别名
├── data/
│   ├── librefang.db           #   SQLite 数据库（记忆、会话、知识图谱）
│   └── state.db               #   守护进程状态持久化
├── registry/                  # 从 librefang-registry 同步
│   ├── agents/                #   32 个 Agent 模板
│   ├── hands/                 #   15 个 Hand 定义
│   ├── providers/             #   49 个 provider 配置
│   ├── skills/                #   技能定义
│   ├── workflows/             #   工作流模板
│   └── plugins/               #   插件定义
├── workspaces/                # 运行时工作目录
│   ├── agents/                #   活跃 Agent 的工作目录
│   └── hands/                 #   活跃 Hand 的工作目录
├── skills/                    # 用户安装的技能
├── plugins/                   # 用户安装的插件
├── vault.enc                  # 加密凭证仓
├── logs/                      # 应用日志
├── cache/                     # 临时缓存
└── bin/                       # CLI 二进制（若通过脚本安装）

完整说明见架构 - 用户数据目录。

配置 API Key

LibreFang 至少需要一个 LLM 供应商的 API Key。作为环境变量设置：

# Anthropic (Claude)
export ANTHROPIC_API_KEY=sk-ant-...

# 或 OpenAI
export OPENAI_API_KEY=sk-...

# 或 Groq（有免费额度）
export GROQ_API_KEY=gsk_...

将 export 写入你的 shell 配置（~/.bashrc、~/.zshrc 等）以便持久化。

LibreFang 支持三层密钥存储（按优先级从高到低）：

层级	文件	设置方式	备注
系统环境变量	—	`export GROQ_API_KEY=...`	最高优先级，不会被覆盖
加密凭证仓	`vault.enc`	`librefang vault set GROQ_API_KEY`	AES 加密，推荐使用
.env 文件	`.env`	`librefang config set-key groq`	明文，由 CLI 写入
secrets.env	`secrets.env`	仪表盘"Set API Key"按钮	明文，由仪表盘写入

编辑配置

默认配置使用 Anthropic。若要更换供应商，编辑 ~/.librefang/config.toml：

[default_model]
provider = "groq"                      # anthropic、openai、groq、ollama 等
model = "llama-3.3-70b-versatile"      # 对应供应商的模型标识符
api_key_env = "GROQ_API_KEY"           # 保存 API 密钥的环境变量

[memory]
decay_rate = 0.05                      # 记忆置信度衰减率

[network]
listen_addr = "127.0.0.1:4545"        # OFP 监听地址

验证配置

librefang doctor

该命令会检查配置文件是否存在、API Key 是否设置、工具链是否就绪。

生成第一个 Agent

使用内置模板

LibreFang 在 registry 中提供了 32 个 Agent 模板（assistant 预装，其他可从仪表盘安装）。生成 hello-world Agent：

librefang agent spawn agents/hello-world/agent.toml

输出：

Agent spawned successfully!
  ID:   a1b2c3d4-e5f6-...
  Name: hello-world

使用自定义清单

创建你自己的 my-agent.toml：

name = "my-assistant"
version = "0.1.0"
description = "A helpful assistant"
author = "you"
module = "builtin:chat"

[model]
provider = "groq"
model = "llama-3.3-70b-versatile"

[capabilities]
tools = ["file_read", "file_list", "web_fetch"]
memory_read = ["*"]
memory_write = ["self.*"]

然后生成：

librefang agent spawn my-agent.toml

列出运行中的 Agent

librefang agent list

输出：

ID                                     NAME             STATE      PROVIDER     MODEL
-----------------------------------------------------------------------------------------------
a1b2c3d4-e5f6-...                     hello-world      Running    groq         llama-3.3-70b-versatile

与 Agent 对话

使用 Agent ID 启动交互式对话：

librefang agent chat a1b2c3d4-e5f6-...

或使用快捷命令（选择第一个可用的 Agent）：

librefang chat

或按名称指定 Agent：

librefang chat hello-world

会话示例：

Chat session started (daemon mode). Type 'exit' or Ctrl+C to quit.

you> Hello! What can you do?

agent> I'm the hello-world agent running on LibreFang. I can:
- Read files from the filesystem
- List directory contents
- Fetch web pages

Try asking me to read a file or look up something on the web!

  [tokens: 142 in / 87 out | iterations: 1]

you> List the files in the current directory

agent> Here are the files in the current directory:
- Cargo.toml
- Cargo.lock
- README.md
- agents/
- crates/
- docs/
...

you> exit
Chat session ended.

启动守护进程

为了支持持久化 Agent、多用户访问和 WebChat 界面，启动守护进程：

librefang start

输出：

Starting LibreFang daemon...
LibreFang daemon running on http://127.0.0.1:4545
Press Ctrl+C to stop.

守护进程提供：

REST API：http://127.0.0.1:4545/api/
WebSocket 端点：ws://127.0.0.1:4545/api/agents/{id}/ws
WebChat 界面：http://127.0.0.1:4545/
OFP 网络：端口 4545

检查状态

librefang status

停止守护进程

在运行守护进程的终端中按 Ctrl+C，或执行：

curl -X POST http://127.0.0.1:4545/api/shutdown

使用 WebChat 界面

守护进程运行时，在浏览器中打开：

http://127.0.0.1:4545/

内嵌的 WebChat 界面允许你：

查看所有运行中的 Agent
通过 WebSocket 与任意 Agent 实时对话
观察流式响应的生成过程
查看每条消息的 Token 使用量

下一步

当你已经运行起 LibreFang：

探索 Agent 模板：浏览 agents/ 目录中的预置 Agent（coder、researcher、writer、ops、analyst、security-auditor 等）。
创建自定义 Agent：编写你自己的 agent.toml 清单。能力与调度详见架构文档。
配置通道：连接 44 种消息平台中的任意一个（Telegram、Discord、Slack、WhatsApp、LINE、Mastodon 及其他 38 个）。见 Channel 适配器。
安装技能：从仪表盘安装 60 个专家知识技能（GitHub、Docker、Kubernetes、安全审计、提示词工程等）。见技能开发。
开发自定义技能：使用 Python、WASM 或 prompt-only 扩展 Agent 能力。见技能开发。
调用 API：230+ 个 REST/WS/SSE 端点，包括 OpenAI 兼容的 /v1/chat/completions。见 API 参考。
切换 LLM 供应商：支持 49 种驱动（Anthropic、OpenAI、Gemini、Groq、DeepSeek、xAI、Ollama 等）。支持按 Agent 覆盖模型。
搭建工作流：串联多个 Agent。使用 librefang workflow create 加 TOML 工作流定义。
使用 MCP：通过 Model Context Protocol 连接外部工具。在 config.toml 的 [[mcp_servers]] 中配置。
从 OpenFang 迁移：运行 librefang migrate --from openfang，会把 ~/.openfang 复制到 ~/.librefang 并自动改写内容。
从 OpenClaw 迁移：运行 librefang migrate --from openclaw。见 MIGRATION.md。
桌面应用：运行 cargo tauri dev 体验带系统托盘的原生桌面版。
运行诊断：librefang doctor 检查整个环境。

常用命令速查

librefang init                          # 初始化 ~/.librefang/
librefang start                         # 启动守护进程
librefang status                        # 检查守护进程状态
librefang doctor                        # 运行诊断

librefang agent spawn <manifest.toml>   # 生成 Agent
librefang agent list                    # 列出所有 Agent
librefang agent chat <id>               # 与 Agent 对话
librefang agent kill <id>               # 终止 Agent

librefang workflow list                 # 列出工作流
librefang workflow create <file.json>   # 创建工作流
librefang workflow run <id> <input>     # 运行工作流

librefang trigger list                  # 列出事件触发器
librefang trigger create <args>         # 创建触发器
librefang trigger delete <id>           # 删除触发器

librefang skill install <source>        # 安装技能
librefang skill list                    # 列出已安装的技能
librefang skill search <query>          # 在 FangHub 中搜索
librefang skill create                  # 生成技能脚手架

librefang channel list                  # 列出 Channel 状态
librefang channel setup <channel>       # 交互式配置向导

librefang config show                   # 查看当前配置
librefang config edit                   # 在编辑器中打开配置

librefang chat [agent]                  # 快速对话（别名）
librefang migrate --from openfang       # 从 OpenFang 迁移
librefang migrate --from openclaw       # 从 OpenClaw 迁移
librefang mcp                           # 启动 MCP 服务器（stdio）