快速开始

要求 Node.js ≥ 18，无其他外部依赖。三步启动：

# 1. 安装依赖
npm install

# 2. 生成配置（务必修改 token！）
cp config.example.json config.json

# 3. 启动
npm start

启动后可访问：

• Web 控制台：http://localhost:7800/（填入 token 即可连接）
• WS 通道：ws://localhost:7800/ws?token=<TOKEN>
• 健康探针：http://localhost:7800/health

MCP 接入

FreeX 自带标准 MCP 桥（mcp/freex-mcp.mjs），在 ZCode / Claude Desktop / Cursor 等任何支持 MCP 的客户端中加入以下配置，重启后即可获得 48 个 freex_ 前缀工具：

{
  "mcpServers": {
    "freex-ai-server": {
      "command": "node",
      "args": ["<项目绝对路径>/mcp/freex-mcp.mjs"],
      "env": {
        "FREEX_WS_URL": "ws://127.0.0.1:7800/ws",
        "FREEX_TOKEN": "<你的 admin token>"
      }
    }
  }
}

线上生产环境改用 TLS 地址 wss://your-domain/ws（见部署指南）。

角色与凭据

token 在服务端 config.json 的 tokens 中配置，可配多个、随时轮换：

工具速查（48 个）

所有工具以 freex_ 为前缀，按模块分组：

WebSocket 协议

所有消息为 JSON 文本帧，统一信封 {"v":1, ...}。三种交互模式：req/res（请求-响应）、stream（流式过程输出）、push（订阅广播）。

客户端 → 服务端

服务端 → 客户端

大文件走 HTTP 通道（token 鉴权不变）：GET /api/fs/download?path=&token=、PUT /api/fs/upload?path=&token=（≤200MB）。

错误码

错误统一为 {code, message} 结构化数据，AI 可编程重试或换方案：

AUTH_REQUIRED AUTH_FAILED FORBIDDEN_ROLE RATE_LIMITED UNKNOWN_ACTION BAD_REQUEST EXEC_BLOCKED EXEC_TIMEOUT EXEC_OUTPUT_LIMIT FS_OUT_OF_ROOT FS_TOO_LARGE PKG_MANAGER_NOT_FOUND DOCKER_NOT_FOUND DESKTOP_UNAVAILABLE INTERNAL

配置参考

配置文件 config.json 主要项（完整示例见 config.example.json）：

安全模式怎么选

三种模式都与这些机制叠加生效：fsRoot 路径沙箱、超时杀进程树、限流、IP 白名单、全量审计、删除前自动快照。

部署指南

Linux（systemd）

项目放 /opt/freex_ai_server 后：

sudo cp scripts/freex.service /etc/systemd/system/
sudo systemctl enable --now freex

Windows 服务

安装 nssm 后以管理员运行 scripts\install-windows-service.ps1；或通用方案 pm2 start src/index.js --name freex && pm2 save。

TLS 反代（Caddy，最简）

freex.example.com {
    reverse_proxy /ws  127.0.0.1:7800
    reverse_proxy      127.0.0.1:7800
}

Caddy 自动签发并续期 Let's Encrypt 证书，WebSocket 升级头自动透传。Nginx 需为 /ws 开启 proxy_http_version 1.1 与 Upgrade/Connection 头。客户端改用 wss:// 地址。

SSH 隧道（零端口暴露，推荐先做）

ssh -L 7800:127.0.0.1:7800 user@<服务器IP>
# 之后所有客户端连 ws://127.0.0.1:7800/ws，公网无需开任何端口

常见问题

连接失败？

检查 Node ≥ 18、token 是否正确、网络是否可达；公网直连时确认云厂商安全组已放行对应 TCP 端口（Windows 防火墙脚本可自动放行）。

工具返回 AUTH_FAILED？

token 被轮换，向管理员索取新 token。

工具返回 FORBIDDEN_ROLE？

当前 token 是 viewer 只读角色，需要 admin 请联系管理员。

AI 能造成多大破坏？

取决于你给的模式与角色：viewer 无法写操作；blocklist 拦截已知危险命令；allowlist 只放行白名单；confirm 模式高危操作必须人工批准；删除类操作自动快照、可一键回滚；所有操作全程审计。详见安全模式。

更新服务要重启吗？

Web 控制台页面与静态资源按请求即时读取，覆盖即生效；src/ 与 config.json 改动需重启服务。