FreeLLMAPI部署教程+配置opencode

FreeLLMAPI 是一个开源的 OpenAI 兼容代理服务。它的核心作用是聚合多家AI服务商的免费额度，将这些分散的“小水管”汇集成一个统一的API 接口，让开发者能轻松调用海量的免费AI 模型 。

配置到 opencode 后，只需一个 统一 key 即可自动切换最优免费模型，无需手动管理多个 provider key。

一、安装 FreeLLMAPI

Windows

桌面版（推荐）

从 ReleHub Releases 下载 FreeLLMAPI-Setup-x.x.x.exe，双击安装。系统托盘图标提供 Open Dashboard 和 Copy Key 功能。

数据位置：%APPDATA%\FreeLLMAPI\

Docker

1
2
3
4
5
6
7
8
9
10
11
# 第 1 步
git clone https://github.com/tashfeenahmed/freellmapi.git
# 第 2 步
cd freellmapi
# 第 3 步
$Bytes = New-Object Byte[] 32
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($Bytes)
$ENCRYPTION_KEY = -join ($Bytes | ForEach-Object { "{0:x2}" -f $_ })
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
# 第 4 步
docker compose up -d

源码运行

1
2
3
4
5
6
7
8
9
# 第 1 步
git clone https://github.com/tashfeenahmed/freellmapi.git
# 第 2 步
cd freellmapi && npm install
# 第 3 步
$ENCRYPTION_KEY = node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
"ENCRYPTION_KEY=$ENCRYPTION_KEY`nPORT=3001" | Out-File -Encoding utf8 .env
# 第 4 步
npm run dev

Dev UI: http://localhost:5173 | API: http://localhost:3001/v1

macOS

桌面版（推荐）

从 Releases 下载 FreeLLMAPI-x.x.x-arm64.dmg，拖入 Applications 后启动，菜单栏图标提供 Copy Key。

数据位置：~/Library/Application Support/FreeLLMAPI/

Docker / 源码

1
2
3
4
5
6
7
8
9
10
11
# 第 1 步
git clone https://github.com/tashfeenahmed/freellmapi.git
# 第 2 步
cd freellmapi
# 第 3 步
ENCRYPTION_KEY="$(openssl rand -hex 32)"  # Docker
# 或：ENCRYPTION_KEY="$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')"  # 源码
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env
# 第 4 步
docker compose up -d
# 或：npm install && npm run dev  # 源码

Linux

一键脚本（Docker，推荐）

适用于任何支持 Docker 的发行版：

1
curl -fsSL https://freellmapi.co/install.sh | bash

输出 FreeLLMAPI is running. Dashboard http://localhost:3001 即成功。

自定义安装：

1
2
3
FREELLMAPI_DIR=/opt/freellmapi curl -fsSL https://freellmapi.co/install.sh | bash  # 自定义目录
PORT=8080 curl -fsSL https://freellmapi.co/install.sh | bash                       # 自定义端口
HOST_BIND=0.0.0.0 curl -fsSL https://freellmapi.co/install.sh | bash              # 绑定局域网

Debian / Ubuntu 手动安装 Docker

1
2
3
4
5
6
7
8
9
10
# 第 1 步：安装 Docker
sudo apt update
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin
sudo usermod -aG docker $USER && newgrp docker
# 第 2 步：安装 FreeLLMAPI
curl -fsSL https://freellmapi.co/install.sh | bash

源码部署（适合低配 ARM 设备，如树莓派、Mobian）

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
# 第 1 步：安装依赖
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs git openssl
# 第 2 步：克隆项目
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi
# 第 3 步：安装依赖并构建
npm install
npm run build
# 第 4 步：生成配置文件
cp .env.example .env
echo "ENCRYPTION_KEY=$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')" >> .env
echo "PORT=3001" >> .env
# 第 5 步：测试运行
npm run dev

二、添加提供商 Key

密钥-添加密钥-添加提供商key，按回车确认。健康检查，绿色对勾即表示可用。

Provider Key 获取地址
Google (Gemini) https://aistudio.google.com
Groq https://console.groq.com
OpenCode Zen https://opencode.ai/zen
OpenRouter https://openrouter.ai
GitHub Models https://github.com/marketplace/models
NVIDIA NIM https://build.nvidia.com
Cloudflare https://developers.cloudflare.com/workers-ai
HuggingFace https://huggingface.co/settings/tokens
Mistral https://console.mistral.ai
Cohere https://dashboard.cohere.com

三、获取API Key

密钥-统一api密钥

四、配置 opencode

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "freellmapi": {
      "name": "FreeLLMAPI",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:3001/v1",
        "apiKey": "freellmapi-你的统一-key"
      },
      "models": {
        "auto": { "name": "自动路由" }
      }
    }
  },
  "disabled_providers": ["openai"]
}

npm 必须为 @ai-sdk/openai-compatible，apiKey 填从 Dashboard 复制的 统一 key。配置后重启 opencode 生效。

五、使用

模型标识 说明
freellmapi/auto 自动路由最优模型（推荐）
freellmapi/gemini-2.5-flash 指定 Google Gemini
freellmapi/deepseek-v4-flash 指定 OpenCode DeepSeek V4 Flash

验证：Dashboard → Analytics 查看请求路由到的 provider 和模型。

六、低配 ARM 设备专项

以下在 512MB RAM 骁龙 410 设备（Debian）上实测通过，适合树莓派、4G 随身 WiFi 等低配 ARM 设备。

设备配置

项目 数值 结论
CPU 骁龙410 ✅ 完美兼容
内存 460MiB (约 512MB) ⚠️ 紧张，需 swap 优化
Swap 原有 230MiB ⚠️ 太小，需扩容到 1GB
磁盘剩余 4G ✅ 足够

步骤一：修复 apt 源

Mobian 官方源密钥已过期，切到国内镜像：

1
2
sudo mv /etc/apt/sources.list.d/mobian.list /etc/apt/sources.list.d/mobian.list.bak
sudo apt update

遇到 apt-transport-https 缺失：sudo apt install apt-transport-https

步骤二：扩容 swap

Node.js 编译需要充足 swap，512MB 设备必须操作：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 第 1 步
# 关闭现有交换
sudo swapoff -a

# 第 2 步
# 创建 1GB 交换文件（约 64 秒）
sudo dd if=/dev/zero of=/swapfile bs=1M count=1024 status=progress

# 第 3 步
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# 第 4 步
# 验证
free -h
# 期望：交换 total 1.0Gi

步骤三：安装编译工具链

FreeLLMAPI 依赖 better-sqlite3，需要从源码编译：

1
sudo apt install -y build-essential python3

安装时如果出现 Which services should be restarted?，输入 21（none of the above）跳过。

步骤四：克隆并安装依赖

1
2
3
4
5
6
7
8
cd /opt
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# npm 下载慢可先切换镜像
npm config set registry https://registry.npmmirror.com

npm install

常见报错：

报错 解决
make: command not found sudo apt install -y make
better-sqlite3 编译失败 sudo apt install -y build-essential python3
package.json not found 确认在 /opt/freellmapi 目录下

步骤五：配置并启动

1
2
3
4
5
6
7
8
9
10
11
12
13
# 第 1 步：生成配置文件
cp .env.example .env
echo "ENCRYPTION_KEY=$(node -e 'console.log(require("crypto").randomBytes(32).toString("hex"))')" >> .env
echo "PORT=3001" >> .env
# 限制 Node.js 堆内存为 256MB（512MB 设备必须，防止 OOM）
echo "NODE_OPTIONS=--max-old-space-size=256" >> .env

# 第 2 步：构建
npm run build

# 第 3 步：测试前台运行
npm run dev
# 看到 Server is running on port 3001 即成功

步骤六：配置 systemd 后台服务

前台运行成功后（Ctrl+C 停止），改为后台运行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 第 1 步：停止前台进程
sudo pkill -f "node server/dist/index.js"

# 第 2 步：创建服务文件
sudo tee /etc/systemd/system/freellmapi.service > /dev/null << 'EOF'
[Unit]
Description=FreeLLMAPI Proxy Service
After=network.target

[Service]
Type=simple
User=root
WorkingDirectory=/opt/freellmapi
ExecStart=/usr/bin/node /opt/freellmapi/server/dist/index.js
Restart=always
RestartSec=5
Environment=PORT=3001
Environment=NODE_OPTIONS=--max-old-space-size=256
EnvironmentFile=-/opt/freellmapi/.env

[Install]
WantedBy=multi-user.target
EOF

# 第 3 步：启动并设置开机自启
sudo systemctl daemon-reload
sudo systemctl enable --now freellmapi

步骤七：验证运行

1
2
3
4
5
6
7
8
9
10
11
# 检查状态
sudo systemctl status freellmapi
# 期望：active (running)

# 检查端口
sudo ss -tlnp | grep 3001
# 期望：node 进程在 :3001 监听

# 获取首次设置验证码
sudo journalctl -u freellmapi -n 20 --no-pager | grep "setup code"
# 期望：First-run setup code: XXXXXXXX

访问 http://<设备IP>:3001，按日志中的验证码创建管理员账号，进入 Keys 页面添加 provider key，获取 统一 key 填入 opencode 配置。

后续管理命令

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 查看状态 / 日志
sudo systemctl status freellmapi
sudo journalctl -u freellmapi -f

# 停止 / 启动 / 重启
sudo systemctl stop freellmapi
sudo systemctl start freellmapi
sudo systemctl restart freellmapi

# 更新
sudo systemctl stop freellmapi
cd /opt/freellmapi && git pull && npm install && npm run build
sudo systemctl start freellmapi

# 查看设备负载
uptime && free -h

内网穿透cloudflare

低配设备额外优化

1
2
# 关闭不必要的服务释放内存
sudo systemctl stop bluetooth cups

七、常见问题

FreeLLMAPI 和直接用 provider 额度一样吗？

一样。FreeLLMAPI 是转发层，不创造额外额度。价值在于自动切换：某个 provider 限流后自动换到下一个，无需手动配置多个 key。

opencode 配置改完不生效？

opencode 启动时加载配置，修改后需完全退出重启。

如何验证 FreeLLMAPI 正常运行？

1
curl http://localhost:3001/api/ping   # 返回 OK

如何更新？

部署方式 更新命令
Docker cd ~/freellmapi && docker compose pull && docker compose up -d
桌面版 下载新版安装器覆盖安装
源码 git pull && npm install && npm run build && node server/dist/index.js

如何备份数据？

备份 ~/freellmapi/.env（含加密密钥）和 Docker volume 中的 SQLite 数据库。

参考链接

资源 链接
FreeLLMAPI GitHub https://github.com/tashfeenahmed/freellmapi
在线模型目录 https://freellmapi.co/models
opencode 配置 Schema https://opencode.ai/config.json
OpenCode Zen https://opencode.ai/zen