快速上手

安装方式概览

OpenFang 支持五种主要安装方式：桌面应用、Shell 脚本安装器、PowerShell 安装器、Cargo 源码编译和 Docker 容器部署。根据操作系统和具体需求，可以选择最适合的安装路径。

安装方式	适用平台	特点
桌面应用	Windows / macOS / Linux	包含原生窗口、系统托盘、自动更新和系统通知
Shell 脚本	Linux / macOS / WSL	自动检测平台、验证校验和、配置 PATH
PowerShell	Windows	自动检测架构、验证签名、配置用户 PATH
Cargo	全平台	从源码编译，需要 Rust 1.75+
Docker	全平台	容器化部署，适合服务端场景

根据 docs/getting-started.md:17-90 的说明，桌面应用提供最完整的用户体验，而 CLI 安装器则更适合开发者和自动化场景。

环境要求

操作系统支持

Shell 安装脚本支持以下平台组合（scripts/install.sh:14-39）：

Linux：x86_64-unknown-linux-gnu、aarch64-unknown-linux-gnu
macOS：x86_64-apple-darwin、aarch64-apple-darwin

Windows 平台支持（scripts/install.ps1:22-60）：

Windows：x86_64-pc-windows-msvc、aarch64-pc-windows-msvc

依赖项

Shell 安装器：需要 curl、sha256sum 或 shasum（用于校验和验证）
PowerShell 安装器：Windows PowerShell 5.1+ 或 PowerShell Core 7+
Cargo 安装：Rust 1.75+ 工具链
Docker 安装：Docker Engine 20.10+

可选依赖

Git：用于从源码克隆和构建
环境变量：ANTHROPIC_API_KEY、OPENAI_API_KEY 或 GROQ_API_KEY（用于 LLM Provider）

Linux 与 macOS 安装流程

使用 Shell 脚本安装

Shell 安装器是 Linux 和 macOS 平台的推荐 CLI 安装方式。执行以下命令即可完成安装：

bash
1curl -sSf https://openfang.sh | sh

根据 scripts/install.sh:1-12，该脚本支持通过环境变量自定义安装：

bash
1# 自定义安装目录
2OPENFANG_INSTALL_DIR=/opt/openfang curl -sSf https://openfang.sh | sh
3
4# 安装特定版本
5OPENFANG_VERSION=v0.1.0 curl -sSf https://openfang.sh | sh

平台检测机制

安装脚本会自动检测操作系统和 CPU 架构（scripts/install.sh:14-39）：

通过 uname -s 获取操作系统类型（linux/darwin）
通过 uname -m 获取 CPU 架构（x86_64/aarch64）
组合生成目标平台标识符（如 x86_64-unknown-linux-gnu）

如果检测到 Windows 环境（mingw/msys/cygwin），脚本会提示用户使用 PowerShell 安装器或下载 MSI 包。

下载与校验

安装流程包含完整的版本获取和校验机制（scripts/install.sh:49-84）：

从 GitHub API 获取最新 release 版本号
下载对应平台的预编译二进制包
下载 SHA256 校验和文件

校验和验证流程（scripts/install.sh:86-111）：

优先使用 sha256sum 命令
macOS 回退到 shasum -a 256
如果两者都不可用，跳过验证并提示警告

PATH 环境变量配置

安装脚本会自动检测用户的默认 Shell 并配置相应的配置文件（scripts/install.sh:132-175）：

Shell	配置文件
zsh	`~/.zshrc`
bash	`~/.bashrc`
fish	`~/.config/fish/config.fish`

对于 fish shell，使用 fish_add_path 命令；对于 bash/zsh，使用 export PATH 语法。脚本会检测目标配置文件的语法，避免将 bash 语法写入 fish 配置。

macOS 特殊处理

在 Apple Silicon Mac 上，安装脚本会执行额外的代码签名步骤（scripts/install.sh:113-130）：

使用 xattr -cr 移除隔离属性
使用 codesign --force --sign - 进行临时签名

这些步骤可以防止 macOS Gatekeeper 终止未签名二进制文件的执行。

Windows 安装流程

使用 PowerShell 安装器

在 Windows 平台上，使用 PowerShell 安装器进行 CLI 安装：

powershell
1irm https://openfang.sh/install.ps1 | iex

或者使用完整 URL：

powershell
1powershell -c "irm https://openfang.sh/install.ps1 | iex"

根据 scripts/install.ps1:1-14，支持通过环境变量自定义安装：

powershell
1$env:OPENFANG_INSTALL_DIR = "C:\Tools\OpenFang"
2$env:OPENFANG_VERSION = "v0.1.0"
3irm https://openfang.sh/install.ps1 | iex

架构检测机制

PowerShell 安装器使用多种方法检测 CPU 架构（scripts/install.ps1:22-60）：

方法 1：.NET RuntimeInformation.OSArchitecture
方法 2：环境变量 PROCESSOR_ARCHITECTURE
方法 3：WMI Win32_Processor.Architecture 属性
方法 4：IntPtr.Size 指针大小回退（8 字节 = 64 位）

这种多重检测机制确保在各种 PowerShell 托管环境下都能正确识别架构。

下载与校验

Windows 安装流程（scripts/install.ps1:80-114）：

构建下载 URL（openfang-{arch}-pc-windows-msvc.zip）
下载 ZIP 压缩包到临时目录
下载 SHA256 校验和文件

校验和验证（scripts/install.ps1:116-136）：

使用 Get-FileHash cmdlet 计算实际哈希值
与下载的校验和文件进行比对
验证失败时终止安装并清理临时文件

PATH 环境变量配置

安装成功后，脚本会将安装目录添加到用户 PATH 环境变量（scripts/install.ps1:160-166）：

powershell
1# 检查 PATH 中是否已存在
2$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
3if ($currentPath -notlike "*$InstallDir*") {
4    [Environment]::SetEnvironmentVariable("Path", "$InstallDir;$currentPath", "User")
5}

修改后需要重启终端才能生效。

初始化与配置

运行初始化命令

安装完成后，执行初始化命令创建配置目录结构（docs/getting-started.md:93-111）：

bash
1openfang init

该命令会创建以下目录结构：

~/.openfang/
  config.toml    # 主配置文件
  data/          # 数据库和运行时数据
  agents/        # Agent 清单（可选）

安装脚本在完成后会提示用户执行此命令（scripts/install.sh:187-194）。

配置 API Key

OpenFang 需要至少一个 LLM Provider 的 API Key。根据 docs/getting-started.md:112-128，支持以下 Provider：

bash
1# Anthropic (Claude)
2export ANTHROPIC_API_KEY=sk-ant-...
3
4# OpenAI
5export OPENAI_API_KEY=sk-...
6
7# Groq (提供免费额度)
8export GROQ_API_KEY=gsk_...

为使环境变量持久化，需要将 export 命令添加到 shell 配置文件（~/.bashrc、~/.zshrc 等）。

配置文件说明

默认配置使用 Anthropic 作为 LLM Provider。如需更改 Provider，编辑 ~/.openfang/config.toml 文件。配置文件的具体结构需要确认（openfang.toml.example 文件内容未在源文件中提供）。

最短可运行路径

一键安装并启动

对于 Linux/macOS 用户，最短的启动路径如下：

bash
1# 1. 安装
2curl -sSf https://openfang.sh | sh
3
4# 2. 重新加载 shell 配置
5source ~/.bashrc  # 或 ~/.zshrc
6
7# 3. 设置 API Key
8export ANTHROPIC_API_KEY=sk-ant-...
9
10# 4. 初始化
11openfang init
12
13# 5. 验证安装
14openfang --version

Docker 快速启动

使用 Docker 部署的最短路径（docs/getting-started.md:63-74）：

bash
1# 拉取镜像
2docker pull ghcr.io/RightNow-AI/openfang:latest
3
4# 启动容器
5docker run -d \
6  --name openfang \
7  -p 4200:4200 \
8  -e ANTHROPIC_API_KEY=$ANTHROPIC_API_KEY \
9  -v openfang-data:/data \
10  ghcr.io/RightNow-AI/openfang:latest

端口 4200 和数据卷 openfang-data 的用途需要确认（Dockerfile 内容未在源文件中提供）。

运行验证

验证安装成功

安装完成后，使用以下命令验证（docs/getting-started.md:85-90）：

bash
1openfang --version

Shell 安装脚本在安装过程中会自动执行此验证（scripts/install.sh:177-186）：

成功时输出：OpenFang installed successfully! ({version})
失败时输出：OpenFang binary installed to {path}

PowerShell 安装器同样包含验证逻辑（scripts/install.ps1:168-180）。

预期输出

成功安装后，openfang --version 应输出类似以下内容：

openfang 0.1.0

具体版本号格式需要确认（源文件中未提供实际的 --version 输出示例）。

常见问题与排错

问题 1：命令未找到

症状：执行 openfang 命令时提示 command not found

原因：PATH 环境变量未更新或未生效

解决方案：

重新加载 shell 配置：source ~/.bashrc 或 source ~/.zshrc
或者重启终端
验证安装路径：ls ~/.openfang/bin/

手动添加到 PATH：

bash
1export PATH="$HOME/.openfang/bin:$PATH"

问题 2：校验和验证失败

症状：安装过程中提示 Checksum verification FAILED!

原因：下载文件损坏或被篡改

解决方案（scripts/install.sh:97-102）：

清除缓存并重新下载
检查网络连接是否稳定

如果问题持续，使用 Cargo 从源码编译：

bash
1cargo install --git https://github.com/RightNow-AI/openfang openfang-cli

问题 3：macOS 上二进制被终止

症状：在 Apple Silicon Mac 上运行时进程被 SIGKILL 终止

原因：macOS Gatekeeper 阻止未签名二进制执行

解决方案（scripts/install.sh:113-130）：

手动移除隔离属性并重新签名：

bash
1xattr -cr ~/.openfang/bin/openfang
2codesign --force --sign - ~/.openfang/bin/openfang

或在"系统设置 > 隐私与安全性"中允许运行

问题 4：Windows 上架构检测失败

症状：PowerShell 安装器提示 Unsupported architecture

原因：架构检测方法在某些环境下可能失败

解决方案（scripts/install.ps1:54-58）：

使用 Cargo 从源码编译：

powershell
1cargo install --git https://github.com/RightNow-AI/openfang openfang-cli

或从 GitHub Releases 页面手动下载对应架构的 ZIP 包

问题 5：下载失败

症状：提示 Download failed. The release may not exist for your platform

原因：目标平台没有预编译的二进制包

解决方案（scripts/install.sh:79-84）：

使用 Cargo 从源码编译
检查 GitHub Releases 页面确认支持的平台列表

下一步建议

完成安装和初始化后，建议按以下顺序继续探索 OpenFang：

配置 LLM Provider：根据使用场景选择 Anthropic、OpenAI 或 Groq，并在配置文件中进行相应设置
创建第一个 Agent：使用 openfang agent create 命令（具体命令需要确认）创建自定义 Agent
启动守护进程：运行 openfang daemon 启动后台服务（具体命令需要确认）
使用 WebChat UI：通过浏览器访问交互界面（端口和访问路径需要确认）

详细的配置选项、Agent 开发指南和高级功能，请参考"使用指南"和"配置参考"章节。

需要确认的内容：

openfang.toml.example 文件内容 — 用于补充配置文件结构说明
.env.example 文件内容 — 用于补充环境变量配置示例
Dockerfile 内容 — 用于确认 Docker 部署的端口和数据卷配置
Cargo.toml 内容 — 用于确认项目依赖和版本信息
SDK 文件（sdk/python/setup.py、sdk/javascript/index.js）— 用于补充 SDK 安装说明
实际的 openfang --version 输出格式
Agent 创建、守护进程启动、WebChat UI 访问的具体命令和端口

安装方式概览

推荐安装路径

环境要求

操作系统支持

依赖项

可选依赖

Linux 与 macOS 安装流程

使用 Shell 脚本安装

平台检测机制

下载与校验

PATH 环境变量配置

macOS 特殊处理

Windows 安装流程

使用 PowerShell 安装器

架构检测机制

下载与校验

PATH 环境变量配置

初始化与配置

运行初始化命令

配置 API Key

配置文件说明

最短可运行路径

一键安装并启动

Docker 快速启动

运行验证

验证安装成功

预期输出

常见问题与排错

问题 1：命令未找到

问题 2：校验和验证失败

问题 3：macOS 上二进制被终止

问题 4：Windows 上架构检测失败

问题 5：下载失败

下一步建议