AI Skill 使用指南

让大模型直接操作 FLVX 面板的技能包。支持 OpenCode、OpenClaw、Claude Code 等工具。

安装

方式 1: npm (推荐)

npm install -g @flvx/skill-api

postinstall 脚本会自动链接到 ~/.agents/skills/flvx-api/。

方式 2: 手动链接

# 从 FLVX 源码
cd /path/to/flvx
mkdir -p ~/.agents/skills
ln -sf $(pwd)/skills/flvx-api ~/.agents/skills/

# 或从 GitHub
git clone https://github.com/Sagit-chu/flvx.git
cd flvx
ln -sf $(pwd)/skills/flvx-api ~/.agents/skills/

配置

设置环境变量：

export FLVX_BASE_URL="https://your-panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"

或使用凭证文件：

mkdir -p ~/.flvx
cat > ~/.flvx/.env << 'EOF'
export FLVX_BASE_URL="https://panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"
EOF
chmod 600 ~/.flvx/.env
source ~/.flvx/.env

---

工具接入方法

OpenCode

OpenCode 是命令行 AI 编程助手，支持通过 skills 扩展能力。

安装 skill:

npm install -g @flvx/skill-api

使用:

export FLVX_BASE_URL="https://panel.example.com"
export FLVX_USERNAME="admin"
export FLVX_PASSWORD="your-password"

opencode

示例对话:

你: 查看我的转发列表
你: 创建一个转发到 192.168.1.100:80 使用隧道 1
你: 检查节点状态
你: 查看流量使用情况

---

OpenClaw

OpenClaw 同样支持 skills 机制。

安装 skill:

npm install -g @flvx/skill-api

# 或手动链接
mkdir -p ~/.openclaw/skills
ln -sf /path/to/flvx/skills/flvx-api ~/.openclaw/skills/flvx-api

使用:

openclaw

>>> 查看所有节点状态
>>> 给用户 alice 分配 50GB 流量
>>> 导出系统备份

---

Claude Code

Claude Code 是 Anthropic 官方的命令行工具，支持通过 CLAUDE.md 扩展。

方式 1: 项目级 CLAUDE.md

在项目根目录创建 CLAUDE.md：

# FLVX API Skill

你可以通过 REST API 操作 FLVX 面板。

## 环境变量
- FLVX_BASE_URL: 面板地址
- FLVX_USERNAME: 用户名
- FLVX_PASSWORD: 密码

## 认证规则
- Authorization 头使用原始 JWT token，不加 "Bearer " 前缀
- 所有 API 使用 POST 方法

## 常用 API

### 登录获取 token
POST /api/v1/user/login
{"username": "...", "password": "..."}

### 查看转发列表
POST /api/v1/forward/list
Authorization: <token>
{}

### 创建转发
POST /api/v1/forward/create
{"name": "xxx", "tunnelId": 1, "remoteAddr": "1.2.3.4:80"}

### 查看节点
POST /api/v1/node/list
{}

使用:

cd /path/to/your/project
claude

方式 2: 全局 CLAUDE.md

mkdir -p ~/.claude
cat > ~/.claude/CLAUDE.md << 'EOF'
# FLVX Panel Operations

使用 FLVX REST API 操作流量转发面板。

环境变量: FLVX_BASE_URL, FLVX_USERNAME, FLVX_PASSWORD
调用方式: curl -X POST "$FLVX_BASE_URL/api/v1/..." -H "Authorization: $TOKEN"
注意: Authorization 不要加 Bearer 前缀
EOF

方式 3: 复制 SKILL.md

cat ~/.agents/skills/flvx-api/SKILL.md >> ~/.claude/CLAUDE.md

示例对话:

>>> 帮我查看 FLVX 面板上有哪些节点
>>> 创建一个名为 test 的转发，目标地址 10.0.0.1:80
>>> 查看我的流量使用情况

---

API 覆盖

模块	操作
认证	登录、Token 管理
用户	增删改查、流量重置、密码
节点	增删改查、安装、升级、状态
隧道	增删改查、用户分配
转发	增删改查、暂停/恢复、诊断
分组	用户/隧道分组、权限
限速	增删改查
联邦	节点共享、远程节点
备份	导出/导入

安全提示

• ⚠️ 环境变量在进程列表中可见
• 使用 ~/.flvx/.env 文件并设置 chmod 600
• 添加 export HISTIGNORE="*FLVX_PASSWORD*" 防止密码进入历史记录
• Token 仅在会话内存中缓存，不写入磁盘

发布

维护者可通过以下方式发布新版本：

# 方式 1: 推送 tag
git tag skill-v2.1.6
git push --tags

# 方式 2: GitHub Actions 手动触发
# 在 Actions 页面运行 publish-skill workflow

需要在 GitHub 仓库设置 NPM_TOKEN secret。