FotricCalw 安装与配置指南

FotricCalw 是一个轻量级、透明的 AI Agent 系统，支持命令行安装和配置。

系统要求

• Node.js >= 18.0.0
• npm >= 9.0.0

安装方式

方式一：从 npm 安装

npm install -g fotric-claw

安装后直接使用：

# 配置 API
fotric-claw config

# 启动服务
fotric-claw start

npm 安装的版本已预编译，无需构建步骤。

方式二：从源码安装

步骤 1：克隆项目

git clone https://github.com/fotric/fotric-claw.git
cd fotric-claw

步骤 2：安装依赖

npm run install:all

该命令会自动安装前端和后端的所有依赖。

也可以手动安装：

cd backend && npm install
cd ../frontend && npm install

步骤 3：配置环境变量

复制环境变量模板：

cp backend/.env.example backend/.env

或使用命令行配置工具（配置将保存到 backend/.env）：

node bin/fotric-claw.js config

步骤 4：启动服务

开发模式：

node bin/fotric-claw.js start

生产模式：

# 构建
node bin/fotric-claw.js build

# 启动
node bin/fotric-claw.js start:prod

步骤 5：访问应用

打开浏览器访问 http://localhost:3000

命令行配置

FotricCalw 提供了交互式命令行配置工具，方便用户设置 LLM API 参数。

查看帮助

fotric-claw help

npm 安装用户可用命令：

Commands:
  start       Start backend and frontend services
  config      Configure LLM API settings
  help        Show this help message

源码安装用户额外可用命令：

Commands:
  start       Start backend and frontend services (dev mode)
  build       Build backend and frontend for production

配置 LLM API

运行配置命令：

fotric-claw config

系统将显示当前配置并引导您输入新的配置值：

🔧 FotricCalw Configuration

Current configuration:
  API Key: sk-a****bcd
  API Base URL: https://api.openai.com/v1
  Model Name: gpt-4o

Enter API Key (sk-abcd1234):
Enter API Base URL (https://api.openai.com/v1):
Enter Model Name (gpt-4o):

✅ Configuration saved to .env file
   Please restart the server for changes to take effect.

配置参数说明

| 参数 | 环境变量 | 说明 | 默认值 | |------|----------|------|--------| | API Key | FOTRIC_API_KEY | LLM API 密钥 | - | | API Base URL | FOTRIC_API_BASE_URL | API 基础地址 | https://api.openai.com/v1 | | Model Name | FOTRIC_MODEL_NAME | 模型名称 | gpt-4o |

环境变量配置

除了使用命令行工具，您也可以直接编辑 backend/.env 文件：

# 服务器配置
PORT=8002
NODE_ENV=development

# LLM API 配置（支持 OpenAI 兼容接口）
FOTRIC_API_KEY=your_api_key_here
FOTRIC_API_BASE_URL=https://api.openai.com/v1
FOTRIC_MODEL_NAME=gpt-4o

# 项目路径配置
FOTRIC_ROOT_DIR=./
FOTRIC_SKILLS_DIR=./src/skills
FOTRIC_WORKSPACE_DIR=./src/workspace
FOTRIC_SESSIONS_DIR=./src/sessions
FOTRIC_KNOWLEDGE_DIR=../knowledge
FOTRIC_STORAGE_DIR=../storage

# 内存配置
FOTRIC_MAX_MEMORY_CHARS=20000
FOTRIC_MAX_TOKENS=128000

# 工具配置
FOTRIC_SHELL_TIMEOUT=30000
FOTRIC_REPL_TIMEOUT=15000

启动服务

开发模式（仅源码安装）

# 启动后端服务
npm run backend

# 启动前端服务（新终端窗口）
npm run frontend

生产模式

npm 安装用户：

fotric-claw start

源码安装用户：

# 构建项目
node bin/fotric-claw.js build

# 启动生产服务
node bin/fotric-claw.js start:prod

访问服务

启动成功后：

• 前端界面: http://localhost:3000
• 后端 API: http://localhost:8002
• 配置接口: http://localhost:8002/api/config

常见问题

1. 端口被占用

如果默认端口被占用，可以修改 backend/.env 中的 PORT 配置：

PORT=8003

2. API Key 未配置

如果未配置 API Key，后端服务仍可启动，但 AI 对话功能将无法使用。请通过以下方式配置：

fotric-claw config

或在前端界面的设置页面配置。

3. 使用其他 LLM 提供商

FotricCalw 支持所有 OpenAI 兼容的 API 接口，例如：

Azure OpenAI:

FOTRIC_API_BASE_URL=https://your-resource.openai.azure.com/openai/deployments/your-deployment
FOTRIC_API_KEY=your-azure-key

国内 API 代理:

FOTRIC_API_BASE_URL=https://your-proxy.com/v1
FOTRIC_API_KEY=your-api-key

本地部署模型:

FOTRIC_API_BASE_URL=http://localhost:11434/v1
FOTRIC_API_KEY=ollama
FOTRIC_MODEL_NAME=llama2

技术支持

• GitHub: https://github.com/fotric/fotric-claw
• 官网: https://www.fotric.cn/