开始使用

从安装到第一次跑起来

1. 环境要求

交互类能力（音量 / 屏幕 / 键鼠 / 剪贴板 / 桌面提示 / 截图）需要登录用户的桌面会话。Windows 版以服务方式运行时，内核会把这类插件跨会话创建到当前登录用户的会话中，因此服务态下同样可用；只有在该终端没人登录时才不可用（/capabilities 会标注原因）。

2. 获取安装包

• 会员区下载：FoxAgent-Setup-4.3.0.exe（登录官网会员后可见下载入口）
• 或联系我方获取部署包

3. 安装步骤

1. 右键安装包，选择「以管理员身份运行」。
2. 阅读并同意用户协议。
3. 选择安装路径，默认 C:Program FilesFoxAgent。
4. 等待安装完成。安装过程会自动完成四件事：释放内核与 14 个官方插件、放行防火墙端口（42101/42102/42103）、注册并启动 Windows 系统服务 FoxAgent（启动类型「自动」）、清理旧版本写入的开机自启项（避免与服务抢端口）。
5. 点击「完成」。

截图位：安装向导欢迎页 → 安装路径页 → 完成页（见 03-截图/）。

4. 首次启动

• 安装完成后，安装程序会立即注册并启动 Windows 服务 FoxAgent（启动类型「自动」），此后随开机自启，不需要用户登录；异常退出时由系统按恢复策略自动重启。
• 首次启动会自动生成访问令牌，写入配置文件：
• Windows：%ProgramData%FoxAgentconfig.json 的 auth.token 字段
• Linux：/var/lib/FoxAgent/config.json 的 auth.token 字段
• 首次启动时命令行会打印一行提示：已生成访问令牌并写入 …config.json。服务方式运行的日志落在数据目录下的 logskernel.log（Windows 即 %ProgramData%FoxAgentlogskernel.log），超过 8 MiB 自动轮转为 kernel.log.1。

服务管理（均在管理员命令行中执行）：

fox-agent service status      查看服务是否在运行（无需管理员权限）
fox-agent service start       启动服务
fox-agent service stop        停止服务
fox-agent service install     注册服务（安装包已代做，一般无需手工执行）
fox-agent service uninstall   停止并删除服务

Linux 当前为前台模式，直接运行 /opt/FoxAgent/fox-agent 即可（-d 类后台运行请自行配合 nohup 或进程管理器）。

5. 跑通第一步（5 分钟）

第 1 步：确认服务在线

浏览器打开：

http://localhost:42101/health

返回类似下面的内容即表示内核正常：

{"status":"success","version":"fox-agent 4.3.0 ...","time":"..."}

第 2 步：打开 Web 控制台（推荐，最直观）

http://localhost:42101/console/

页面本身就是静态资源、不含数据，所以能直接打开；但页内每个管理请求都要令牌。先在登录框填入配置文件里的 auth.token：

# 取令牌（管理员 PowerShell）
(Get-Content "$env:ProgramDataFoxAgentconfig.json" -Raw | ConvertFrom-Json).auth.token

填入后即可看到：内核版本与运行时长、插件列表（可启停 / 探测 / 卸载 / 上传安装）、能力清单（含不可用原因），以及「功能测试」区。

第 3 步：用「功能测试」跑通第一条命令

在「功能测试」里选择 volume.get → 参数 mac 默认已是 all → 点「执行」，下方会显示内核的原始返回：

{"status":"success","message":"获取音量成功","data":{"muted":false,"volume":59}}

看到这条返回，说明安装成功、内核在跑、插件可用。表单是按插件上报的参数声明自动生成的，换一条命令（比如 input.mouse.move 的 x/y）参数项会跟着变，不需要记参数名。

另一种方式：用命令行下发（命令行端点对回环来源免认证）

curl.exe -X POST http://localhost:42101/ -H "Content-Type: application/json" -d "{"cmd":"volume.get","mac":"all"}"

注意：命令端点默认对回环来源免认证，但高危命令（power.*、screen.*、input.*、clipboard.*、process.kill、timesync.set、notify.toast）即使来自回环也强制要求令牌；管理端点（/admin/*）则一律要求令牌，不接受回环免认证。

6. 常见安装 / 启动失败

已装旧版 ifu Agent 的机器无需卸载：两者端口不冲突，可并行部署、灰度切换。

分享