# LibreFang 快速上手

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

项目官网：[https://librefang.ai/](https://librefang.ai/)

## 目录

- [安装](#installation)
- [配置](#configuration)
- [生成第一个 Agent](#spawn-your-first-agent)
- [与 Agent 对话](#chat-with-an-agent)
- [启动守护进程](#start-the-daemon)
- [使用 WebChat 界面](#using-the-webchat-ui)
- [下一步](#next-steps)

---

## 安装

### CLI

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

**快速安装脚本（推荐）**

Linux / macOS / WSL：
```bash
curl -fsSL https://librefang.ai/install.sh | sh
```

Windows (PowerShell)：
```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（手动安装）**

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

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

```powershell
# 初始化配置
librefang init

# 启动守护进程
librefang start

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

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

**Homebrew (macOS / Linux)**

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

**npm**

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

**pip**

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

**Cargo**

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

或从源码构建（需要 [just](https://github.com/casey/just)）：
```bash
git clone https://github.com/librefang/librefang.git
cd librefang
just install
```

**Docker**

```bash
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：
```bash
git clone https://github.com/librefang/librefang.git
cd librefang/deploy
docker compose up -d
```

**验证安装**

```bash
librefang --version
```

---

### SDK

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

**JavaScript / TypeScript**

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

**Python**

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

**Rust**

```bash
cargo add librefang
```

**Go**

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

---

### 桌面应用

基于 Tauri 2.0 的原生桌面应用。详见 [桌面端](/zh/integrations/desktop)。

**Homebrew Cask**

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

**直接下载**

从 [GitHub Releases](https://github.com/librefang/librefang/releases) 下载：
- **macOS**：`.dmg`（Universal）
- **Windows**：`.msi`
- **Linux**：`.appimage` / `.deb`

---

## 一键云部署

访问 [deploy.librefang.ai](https://deploy.librefang.ai/) 查看全部云部署方式。

### Fly.io

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

### Railway

[![Railway](https://img.shields.io/badge/Railway-Deploy-0B0D0E?logo=railway)](https://railway.com/deploy/Bb7HnN)

### Render

[![Render](https://img.shields.io/badge/Render-Deploy-46E3B7?logo=render)](https://render.com/deploy?repo=https://github.com/librefang/librefang)

### GCP（Terraform）

部署到 GCP 永久免费额度（e2-micro）。详见 [deploy/gcp/README.md](https://github.com/librefang/librefang/tree/main/deploy/gcp)：

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

### Linux systemd

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

---

## 配置

### 初始化

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

```bash
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 二进制（若通过脚本安装）
```

完整说明见 [架构 - 用户数据目录](/zh/architecture#user-data-directory)。

### 配置 API Key

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

```bash
# 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`：

```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 监听地址
```

### 验证配置

```bash
librefang doctor
```

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

---

## 生成第一个 Agent

### 使用内置模板

LibreFang 在 [registry](https://github.com/librefang/librefang-registry/tree/main/agents) 中提供了 32 个 Agent 模板（`assistant` 预装，其他可从仪表盘安装）。生成 hello-world Agent：

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

输出：

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

### 使用自定义清单

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

```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.*"]
```

然后生成：

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

### 列出运行中的 Agent

```bash
librefang agent list
```

输出：

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

---

## 与 Agent 对话

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

```bash
librefang agent chat a1b2c3d4-e5f6-...
```

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

```bash
librefang chat
```

或按名称指定 Agent：

```bash
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 界面，启动守护进程：

```bash
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

### 检查状态

```bash
librefang status
```

### 停止守护进程

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

```bash
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` 清单。能力与调度详见 [架构文档](/zh/architecture)。
- **配置通道**：连接 44 种消息平台中的任意一个（Telegram、Discord、Slack、WhatsApp、LINE、Mastodon 及其他 38 个）。见 [Channel 适配器](/zh/integrations/channels)。
- **安装技能**：从仪表盘安装 60 个专家知识技能（GitHub、Docker、Kubernetes、安全审计、提示词工程等）。见 [技能开发](/zh/agent/skills)。
- **开发自定义技能**：使用 Python、WASM 或 prompt-only 扩展 Agent 能力。见 [技能开发](/zh/agent/skills)。
- **调用 API**：230+ 个 REST/WS/SSE 端点，包括 OpenAI 兼容的 `/v1/chat/completions`。见 [API 参考](/zh/integrations/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](../MIGRATION.md)。
- **桌面应用**：运行 `cargo tauri dev` 体验带系统托盘的原生桌面版。
- **运行诊断**：`librefang doctor` 检查整个环境。

### 常用命令速查

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




