LibreFang 快速上手
本指南将带你安装 LibreFang、配置第一个 LLM 供应商、生成 Agent 并与其对话。
目录
安装
Arch Linux 仓库设置
AUR 账户注册目前暂时不可用，因此 LibreFang 目前通过官方 pacman 仓库发布已签名的 Arch 软件包。
导入并在本地信任 LibreFang 软件包签名密钥：
curl -fsSL https://packages.librefang.ai/librefang.gpg -o /tmp/librefang.gpg
sudo pacman-key --add /tmp/librefang.gpg
sudo pacman-key --finger 2C325B0F88706ED99C45E216DD09DC7D3E70E1E9
sudo pacman-key --lsign-key 2C325B0F88706ED99C45E216DD09DC7D3E70E1E9
将仓库添加到 /etc/pacman.conf：
[librefang]
Server = https://packages.librefang.ai/arch/$arch
仓库只需配置一次，然后在下面对应的章节中仅安装 CLI 或 Desktop 软件包。 这两个软件包相互独立，因此使用 Desktop 应用不需要安装 CLI。 有关软件包详情和 aarch64 支持，请参阅 Arch 仓库文档。
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
Arch Linux (pacman)
sudo pacman -Syu librefang-bin
此命令安装 CLI、守护进程、HTTP API 和 Web Dashboard，不会安装 Desktop 应用。
NixOS（Nix flakes）
# 一次性运行 CLI，不安装任何东西
nix run github:librefang/librefang
# 将 CLI 安装到用户 profile
nix profile install github:librefang/librefang#librefang-cli
librefang-cli 是刻意收窄范围的软件包：它只构建 --package librefang-cli，因此仅 librefang-desktop 才会链接的 Tauri / GTK webview 依赖栈不会进入 CLI 的构建。
flake.nix 中 cliArgs 处的注释说明了为什么要这样拆分——如果不拆分，在没有安装图形依赖栈的原生 NixOS 机器上，nix build .#librefang-cli 会构建失败。
如果希望以声明式方式安装，请将该 flake 添加为系统 flake 的输入，并导入其 NixOS 模块：
{
inputs = {
nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
librefang.url = "github:librefang/librefang";
};
outputs = { nixpkgs, librefang, ... }: {
nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
system = "x86_64-linux";
modules = [
librefang.nixosModules.default
./configuration.nix
];
};
};
}
然后在 configuration.nix 中启用该服务：
{
services.librefang.enable = true;
}
Debian / Ubuntu / deepin
curl -fsSL https://librefang.ai/install.sh | sh
Linux 版 CLI 以完全静态的 musl 构建发布，x86_64-unknown-linux-musl 和 aarch64-unknown-linux-musl 两个目标都是如此；如果 file 没有报告产物是静态链接的，发布 CI 会直接让该任务失败。
安装脚本优先使用这份静态产物，只有当你的架构缺少静态产物时才回退到 glibc 构建。
正因如此，在较老的发行版上宿主机 glibc 的版本高低无关紧要：若某个发行版版本自带的 glibc 早于通用 glibc 构建的编译目标版本，它会直接拒绝那个二进制，而静态构建根本不从宿主机链接 libc。
如果你的架构缺少静态产物、只能用 glibc 构建，可以先用 ldd --version 查一下本机的版本。
LibreFang 不发布 apt 仓库——packaging/ 只提供 Arch 仓库和 AUR 配方。
请用上面的脚本安装 CLI，桌面应用则从 Releases 获取。
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
Kubernetes
单副本有状态部署的 Kustomize manifest，满足 restricted Pod Security Standard：
git clone https://github.com/librefang/librefang.git
cd librefang
kubectl create namespace librefang
kubectl -n librefang create secret generic librefang-auth \
--from-literal=api-key="$(openssl rand -hex 32)" \
--from-literal=vault-key="$(openssl rand -base64 32)" \
--from-literal=dashboard-user=admin \
--from-literal=dashboard-pass="$(openssl rand -hex 24)"
kubectl -n librefang apply -k deploy/kubernetes/base
replicas 必须保持为 1 —— 支持边界、卷所有权要求和探针契约见 deploy/kubernetes/README.md。
验证安装
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
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
Arch Linux (pacman)
完成本页上方的 Arch Linux 仓库设置 后：
sudo pacman -Syu librefang-desktop-bin
Desktop 软件包可独立运行，不需要安装 librefang-bin。
桌面软件包仅支持 x86_64。
在 aarch64 上，请使用 librefang-bin 运行原生服务，或使用 librefang-docker 运行基于 Docker 的 systemd 服务，然后通过 http://127.0.0.1:4545/ 使用 Web Dashboard。
NixOS（Nix flakes）
nix profile install github:librefang/librefang#librefang-desktop
在 NixOS 上，桌面应用是更粗糙的一条路。
它会链接完整的 GTK / webview 闭包（gtk3、libsoup_3、webkitgtk_4_1），因此构建耗时远高于 CLI，而且会走到 CLI 软件包根本不会触及的代码路径。
如果它在你的机器上构建不出来或启动不了，请改为安装 librefang-cli，并通过 http://127.0.0.1:4545/ 使用 Web Dashboard。
Debian / Ubuntu / deepin
.deb 安装包声明的依赖列表是空的（见 crates/librefang-desktop/tauri.conf.json 中的 bundle.linux.deb.depends），所以 apt 不会替你把 webview 依赖栈装上。
请先自己安装这些依赖——下面这一组正是本项目在自己的 Debian 系 CI runner 上安装的依赖集合：
sudo apt-get install -y \
libwebkit2gtk-4.1-dev \
libgtk-3-dev \
librsvg2-dev \
libdbus-1-dev
deepin 自己的软件源里究竟提供的是 libwebkit2gtk-4.1 还是更旧的 4.0 系列，本项目并未验证。
请把上面这条命令当作需要你去核实的对象，而不是一个保证，并且直接向你要安装的那台机器求证。
apt-cache search libwebkit2gtk # 列出你所用发行版实际提供的 webkit2gtk 软件包
pkg-config --list-all | grep -i webkit
librefang doctor # 针对本机的环境体检
如果你的发行版只提供 4.0 系列，上面的依赖就无法被满足。
这种情况下请安装 CLI，并通过 http://127.0.0.1:4545/ 使用 Web Dashboard。
直接下载
从 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 # 列出已配置的通道
librefang channel setup <channel> # 按 schema 走 sidecar 配置
librefang channel reload # 改完 config.toml 后热加载
librefang channel rm <channel> # 删除一条 sidecar + reload
librefang config show # 查看当前配置
librefang config edit # 在编辑器中打开配置
librefang chat [agent] # 快速对话（别名）
librefang migrate --from openfang # 从 OpenFang 迁移
librefang migrate --from openclaw # 从 OpenClaw 迁移
librefang mcp # 启动 MCP 服务器（stdio）