XClawLink

快速开始

工作原理

XClawLink 是一个跨网络的远程任务执行系统，由 5 个核心组件协同工作：

组件	功能定位	最小必要配置
CLI	AI Agent 的命令行入口，发起指令到远程设备	`server.url`、`auth.token`、`cli.device_id`
Relay	公网信令中转，连接 CLI 和 Proxy	`server.port`
Proxy	部署在目标网络边缘，管理 Agent 连接和权限	`relay.url`、`relay.token`、`relay.tenant_id`
Agent	运行在远程目标上，接收并执行命令	`proxy.host`、`proxy.device_id`、`security.otp`、`security.tenant_id`
Portal	Web 管理后台，管理 CLI Token、Proxy Token、设备	浏览器访问即可

流程: CLI → Relay → Proxy → Agent → 执行命令 → 返回结果

智能路由: 默认优先建立 P2P (KCP) 隧道直连，NAT 受限时自动回退 WebSocket 转发。

下载

从下载页面获取对应组件的最新 zip 包。

安装

Proxy

Linux

bash

tar -zxvf xclawlink-proxy-v1.0.0-Beta-linux-amd64.tar.gz
cd proxy-linux-amd64
sudo bash install.sh
# Binary → /usr/local/bin/xclawlink-proxy
# Config → /opt/xclawlink/proxy/config.yaml

Windows（以管理员权限打开 PowerShell — 需要注册计划任务）

bash

Expand-Archive xclawlink-proxy-v1.0.0-Beta-windows-amd64.zip
cd xclawlink-proxy-windows-amd64
.\install.bat
# Binary → C:\Program Files\XClawLink\xclawlink-proxy.exe
# Config → C:\Program Files\XClawLink\config.yaml

Agent

Linux

bash

tar -zxvf xclawlink-agent-v1.0.0-Beta-linux-amd64.tar.gz
cd agent-linux-amd64
sudo bash install.sh
# Binary → /usr/local/bin/xclawlink-agent
# Config → /opt/xclawlink/agent/config.yaml

Windows（以管理员权限打开 PowerShell — 需要注册计划任务）

bash

Expand-Archive xclawlink-agent-v1.0.0-Beta-windows-amd64.zip
cd xclawlink-agent-windows-amd64
.\install.bat

CLI

Linux

bash

tar -zxvf xclawlink-cli-v1.0.0-Beta-linux-amd64.tar.gz
cd cli-linux-amd64
sudo bash install.sh
# Binary → /usr/local/bin/xclawlink
# Config → /opt/xclawlink/cli/config.yaml

Windows（直接运行，无需管理员权限）

bash

Expand-Archive xclawlink-cli-v1.0.0-Beta-windows-amd64.zip
cd cli-windows-amd64
.\install.bat

卸载

bash

# Linux
sudo bash uninstall.sh

# Windows (管理员权限)
.\uninstall.bat

最小配置

安装后运行 config-start 命令交互式配置所有必需参数，无需手动编辑配置文件。

Proxy

bash

# Linux
xclawlink-proxy config-start
# Windows (管理员 PowerShell)
.\xclawlink-proxy.exe config-start

交互菜单：

1. Tenant ID      [not set]
  2. Relay Token    [not set]
  v. Validate       s. Start         q. Quit

必填参数：

Tenant ID — 租户 ID，从 Portal 获取
Relay Token — JWT 令牌，从 Portal → Tokens 获取（支持粘贴、文件路径、环境变量 PROXY_TOKEN）

配置完成自动校验并启动服务。

Agent

bash

# Linux
xclawlink-agent config-start

交互菜单：

1. Proxy Host     [not set]
  2. Device ID      [not set]
  3. OTP            [not set]
  4. Tenant ID      [not set]
  v. Validate       s. Start         q. Quit

必填参数：

Proxy Host — Proxy 服务器 IP/域名
Device ID — Agent 设备 ID，从 Proxy 管理页面获取
OTP — Agent OTP，从 Proxy 管理页面获取
Tenant ID — 租户 ID，从 Portal 获取

CLI

bash

# Linux
xclawlink config-start
# Windows
.\xclawlink.exe config-start

交互菜单：

1. Device ID      [not set]
  2. OTP            [not set]  (optional)
  3. Tenant ID      [not set]
  4. Relay Token    [not set]
  v. Validate       q. Quit

必填参数：

Device ID — CLI 设备标识，从 Portal → Devices → Create CLI 获取
Tenant ID — 租户 ID，从 Portal 获取
Relay Token — JWT 令牌，从 Portal → Tokens 获取（支持粘贴、文件路径、环境变量 CLI_TOKEN）
OTP（可选）— 可在执行命令时通过 --otp 传入

命令行模式：也可以跳过交互菜单，直接通过参数配置：

bash

xclawlink-agent config-start --host 192.168.1.100 --device AGT-001 --otp xxxxxxxx --tenant demo
xclawlink-proxy config-start --tenant demo --token-file /path/token.txt
xclawlink config-start --device CLI-042 --tenant demo --token eyJ...

凭证来源速查

配置项	组件	从哪里获取
`auth.token`	CLI	Portal → Tokens → Create CLI Token
`auth.otp`	CLI	Proxy 管理页面 → CLI OTP
`relay.token`	Proxy	Portal → Tokens → Create Proxy Token
`proxy.device_id`	Agent	Proxy 管理页面 → Create Agent
`security.otp`	Agent	Proxy 管理页面 → Create Agent OTP
`relay.tenant_id`	Proxy	Portal 租户页面
`proxy.host`	Agent	Proxy 服务器 IP/域名
`security.tenant_id`	Agent	Portal 租户页面
`auth.tenant_id`	CLI	Portal 租户页面
`cli.device_id`	CLI	Portal → Devices → Create CLI

CLI 配置

CLI 配置文件

路径: /opt/xclawlink/cli/config.yaml

yaml

server:
  url: "wss://relay.xclawlink.com/ws"

auth:
  token: "<YOUR_JWT_TOKEN>"
  tenant_id: "test-tenant-id"
  otp: "<AGENT_OTP>"

参数	类型	默认值	说明
`server.url`	string	-	Relay WebSocket 地址
`server.timeout`	int	60	连接超时（秒）
`auth.token`	string	-	JWT 令牌
`auth.tenant_id`	string	test-tenant-id	租户 ID
`auth.otp`	string	-	目标 Agent 的 OTP
`output.format`	string	json	输出格式: json / table / text
`output.pretty`	bool	true	格式化 JSON 输出
`encryption.e2e_enabled`	bool	false	端到端加密
`kcp.enabled`	bool	true	KCP 快速传输
`kcp.crypt`	int	1	加密: 0=none, 1=aes
`kcp.mode`	string	fast2	KCP 模式
`cli.device_id`	string	-	CLI 设备标识
`-p` / `--persist`	bool	false	复用 daemon 持久连接（需先 `systemctl start xclawlink-cli`）

执行模式

--shell 和 --sandbox 是独立的两个标志：

模式	`--shell`	`--sandbox`	效果
直接执行 (默认)	无	无	直接 exec，主机环境
主机 Shell	有	无	sh -c，支持管道/重定向
沙箱隔离	有	有	sh -c + 命名空间隔离

bash

# 主机 Shell (管道/重定向)
xclawlink execute my-device "ps -ef | grep nginx > /tmp/nginx.lst" --shell

# 沙箱隔离命令
xclawlink execute my-device "ping 1.1.1.1" --shell --sandbox

# 目标网络白名单
xclawlink execute my-device "curl http://192.168.1.1:8080" --shell --sandbox --target "192.168.1.1:8080/tcp"

Agent 配置

Agent 配置文件

路径: /opt/xclawlink/agent/config.yaml

yaml

proxy:
  url: "wss://192.168.8.168:9443/agent"
  device_id: "<AGT-NNNNNN>"

security:
  token: "<YOUR_JWT_TOKEN>"
  otp: "<AGENT_OTP>"
  tenant_id: "test-tenant-id"

参数	类型	默认值	说明
`proxy.url`	string	-	Proxy WebSocket 地址
`proxy.device_id`	string	-	Agent 设备 ID
`security.otp`	string	-	Agent OTP
`security.tenant_id`	string	test-tenant-id	租户 ID
`security.allowed_dirs`	[]string	["/tmp"]	允许访问的目录
`security.max_command_length`	int	4096	命令最大长度
`kcp.enabled`	bool	true	KCP 快速传输
`kcp.proxy_addr`	string	-	Proxy KCP 地址
`system.max_concurrent_commands`	int	4	最大并发命令数
`system.command_timeout_seconds`	int	300	命令超时（秒）

Proxy 配置

Proxy 配置文件

路径: /opt/xclawlink/proxy/config.yaml

yaml

relay:
  url: "wss://relay.xclawlink.com/ws"
  token: "<YOUR_JWT_TOKEN>"
  tenant_id: "test-tenant-id"

kcp:
  listen_addr: ":3480"
  cli_listen_port: 3481

p2p:
  public_ip: "<YOUR_PUBLIC_IP>"

参数	类型	默认值	说明
`relay.url`	string	-	Relay WebSocket 地址
`relay.token`	string	-	JWT 令牌
`relay.tenant_id`	string	test-tenant-id	租户 ID
`internal.host`	string	0.0.0.0	监听地址
`internal.port`	int	9443	监听端口
`kcp.enabled`	bool	true	KCP 服务器
`kcp.listen_addr`	string	:3480	Agent KCP 监听地址
`kcp.cli_listen_port`	int	3481	CLI KCP 端口
`p2p.enabled`	bool	true	P2P 隧道
`p2p.public_ip`	string	-	Proxy 公网 IP
`management.enabled`	bool	true	管理页面
`management.addr`	string	:8081	管理页面地址

TLS 证书认证

所有组件默认使用系统信任存储验证 Let's Encrypt 证书。Proxy 首次启动自动生成自签名证书。

yaml

# proxy/config.yaml
relay:
  url: "wss://relay.xclawlink.com/ws"
  tls_ca: ""  # 空 = 系统信任存储

# agent/config.yaml
encryption:
  tls_ca_path: ""  # 空 = 系统信任存储

生产部署: Relay/Portal 使用 Let's Encrypt 通配符证书，Proxy 首次启动自动生成自签名 ECDSA P-256 证书。

使用手册

CLI 命令速查

CLI 安装并 config-start 配置完成后，即可使用以下命令。所有需要操作 Agent 的命令都需要目标 Agent 的 OTP（可在命令中用 --otp 传入，或预先写入配置文件的 auth.otp）。

命令	用法	说明
`version`	`xclawlink version`	查看 CLI 版本号
`devices`	`xclawlink devices`	列出在线的 Agent 设备
`info`	`xclawlink info <device-id>`	查看 Agent 的系统信息（CPU、内存、磁盘）
`execute`	`xclawlink execute <device-id> <command>`	在 Agent 上执行命令
`upload`	`xclawlink upload <device-id> <本地文件> <远端路径>`	上传文件到 Agent
`download`	`xclawlink download <device-id> <远端文件> <本地路径>`	从 Agent 下载文件
`schedules list`	`xclawlink schedules list <device-id>`	查看定时任务列表
`schedules cancel`	`xclawlink schedules cancel <device-id> <task-id>`	取消定时任务
`schedules status`	`xclawlink schedules status <device-id> [task-id]`	查看任务执行状态
`update`	`xclawlink update`	检查并安装 CLI 更新

常用标志

标志	说明
`--otp <OTP>`	目标 Agent 的 OTP，也可通过环境变量 `CLI_OTP` 或配置文件 `auth.otp` 设置
`--shell`	通过 Shell 执行命令，支持管道和重定向
`--sandbox`	命名空间隔离执行（需配合 `--shell`）
`--target "IP:端口"`	网络白名单限制，命令只能访问指定地址
`--dry-run`	预览模式，看效果不实际执行
`--progress <0\|bar\|N>`	上传/下载进度条：`0` 关闭、`bar` 图形进度条、整数 N 表示每 N%输出 JSON
`--persist` / `-p`	通过 daemon 持久连接执行（需先启动 daemon）
`--output json\|table\|text`	输出格式，默认 json
`--confirm <ID>`	审批 ID，用于高危操作确认

CLI 常用场景

场景 1：执行远程命令

bash

# 基本命令
xclawlink execute AGT-000011 "ls -la /opt"

# Shell 模式（支持管道和重定向）
xclawlink execute AGT-000011 "ps -ef | grep nginx > /tmp/nginx.lst" --shell

# 沙箱隔离执行
xclawlink execute AGT-000011 "ping 8.8.8.8" --shell --sandbox

# 网络白名单限制
xclawlink execute AGT-000011 "curl http://192.168.1.1:8080" --shell --sandbox --target "192.168.1.1:8080/tcp"

# 预览模式（不实际执行）
xclawlink execute AGT-000011 "rm -rf /tmp/cache" --dry-run

场景 2：上传文件到 Agent

bash

# 基本上传
xclawlink upload AGT-000011 ./local-file.txt /tmp/remote-file.txt

# 大文件带进度条
xclawlink upload AGT-000011 ./bigfile.tar.gz /tmp/bigfile.tar.gz --progress bar

# 验证上传完整性：在 Agent 上执行 md5sum 对比
xclawlink execute AGT-000011 "md5sum /tmp/remote-file.txt" --shell
md5sum ./local-file.txt

场景 3：从 Agent 下载文件

bash

# 基本下载
xclawlink download AGT-000011 /tmp/remote-file.txt ./downloaded-file.txt

# 带进度条
xclawlink download AGT-000011 /tmp/bigfile.tar.gz ./bigfile.tar.gz --progress bar

# 验证下载完整性
md5sum ./downloaded-file.txt
xclawlink execute AGT-000011 "md5sum /tmp/remote-file.txt" --shell

场景 4：查看设备状态

bash

# 列出所有在线 Agent
xclawlink devices

# 查看特定 Agent 的系统信息
xclawlink info AGT-000011

场景 5：创建和管理定时任务

bash

# 创建定时任务（指定时间执行）
xclawlink execute AGT-000011 "df -h" --mode scheduled --at "2026-08-05 02:00:00"

# 创建循环任务（每 5 分钟）
xclawlink execute AGT-000011 "free -m" --mode interval --every 5m --count 10

# 查看定时任务
xclawlink schedules list AGT-000011

# 查看任务执行状态（实时跟踪）
xclawlink schedules status AGT-000011 task_xxx --follow

# 取消任务
xclawlink schedules cancel AGT-000011 task_xxx

CLI Daemon 持久模式

Daemon 在后台维持持久连接，避免每次命令都重新建立连接，适合频繁操作场景。daemon 为 user 级别 systemd 服务，以当前用户身份运行。

bash

# 启动 daemon
xclawlink daemon start

# 查看 daemon 状态
xclawlink daemon status

# 停止 daemon
xclawlink daemon stop

Linux 下 daemon 为 user 级别 systemd 服务（systemctl --user），Windows 下为后台进程。
Daemon 空闲超时默认 30 分钟（配置项 daemon.idle_timeout），超时后自动关闭。
Daemon 日志：Linux ~/.xclawlink/cli.log，Windows %USERPROFILE%\.xclawlink\cli.log。

启动 daemon 后，其他命令可加 -p（--persist）标志走持久连接：

bash

xclawlink devices -p
xclawlink execute AGT-000011 "uptime" -p
xclawlink upload AGT-000011 ./file.txt /tmp/file.txt -p --progress bar

CLI 自更新

bash

# 检查是否有新版本
xclawlink update --check

# 交互式更新（确认后下载安装）
xclawlink update

# 跳过确认直接更新
xclawlink update -y

Agent 运维与更新

Agent 安装后注册为 user 级别 systemd 服务，安装目录 $HOME/xclawlink/agent/。

bash

# 查看服务状态
systemctl --user status xclawlink-agent

# 启动 / 停止 / 重启
systemctl --user start xclawlink-agent
systemctl --user stop xclawlink-agent
systemctl --user restart xclawlink-agent

# 查看实时日志
tail -f $HOME/xclawlink/agent/agent.log

# 查看版本
xclawlink-agent version

Agent 为被动服务，无需用户直接操作。所有命令通过 CLI 经 Proxy 转发执行。

Agent 自更新

bash

# 检查是否有新版本
xclawlink-agent update --check

# 交互式更新（自动停止服务、替换二进制、重启服务）
xclawlink-agent update

# 跳过确认
xclawlink-agent update -y

# Agent 无 Internet 时通过 Proxy 中转下载
xclawlink-agent update --relay

更新流程自动处理：下载 → 停止服务 → 迁移数据库 → 备份旧二进制(.bak) → 替换 → 重启服务。

Proxy 运维与更新

Proxy 安装后注册为 user 级别 systemd 服务，安装目录 $HOME/xclawlink/proxy/。

Linux

bash

# 查看服务状态
systemctl --user status xclawlink-proxy

# 启动 / 停止 / 重启
systemctl --user start xclawlink-proxy
systemctl --user stop xclawlink-proxy
systemctl --user restart xclawlink-proxy

# 查看实时日志
tail -f $HOME/xclawlink/proxy/proxy.log

# 查看版本
xclawlink-proxy version

Windows（管理员权限 PowerShell）

Proxy 安装时通过 sc create 注册为系统服务 XClawLinkProxy，安装目录 %USERPROFILE%\xclawlink\proxy\。

powershell

# 查看服务状态
sc query XClawLinkProxy

# 启动 / 停止
sc start XClawLinkProxy
sc stop XClawLinkProxy

# 查看日志（安装目录下）
Get-Content $env:USERPROFILE\xclawlink\proxy\proxy.log -Tail 50

# 查看版本
& "$env:USERPROFILE\xclawlink\proxy\xclawlink-proxy.exe" version

Proxy 管理页面

安装完成后，通过浏览器访问管理页面：

地址	说明
`http://localhost:8081`	本机访问
`http://<proxy-ip>:8081`	局域网内其他机器访问

管理页面功能包括：Agent 设备管理、CLI 会话管理、OTP 管理、资源策略配置、操作审计日志等。

登录凭据请联系管理员获取。

Proxy 自更新

bash

# 检查是否有新版本
xclawlink-proxy update --check

# 交互式更新（自动停止服务、替换二进制、重启服务）
xclawlink-proxy update

# 跳过确认
xclawlink-proxy update -y

更新流程自动处理：下载 → 停止服务 → 迁移数据库 → 备份旧二进制(.bak) → 替换 → 重启服务。

安全能力

XClawLink 的安全性建立在三个基础之上，并叠加 AI 智能防护。

三大基础：

基础	说明
传输加密	所有指令和文件传输全程加密，防止窃听
身份认证	多重验证，确保只有授权用户和设备能接入
操作审计	每次操作完整记录，可追溯、可导出

AI 智能防护：

能力	说明
智能防火墙	自动拦截高危命令，覆盖多种危险操作类型
AI 风险分析	每条命令实时评估风险，自动决定放行或审批
灵活权限	多种运维模式一键切换，适应不同场景
人工审批	高风险操作自动拉起审批，确保关键操作有人把关

CLI 安全命令

功能	命令	作用
预览模式	`--dry-run`	先看效果再执行，避免误操作
隔离执行	`--shell --sandbox`	在隔离环境中运行，不影响主机
网络限制	`--target "IP:端口"`	限制命令只能访问指定地址

Agent 自动保护

保护机制	效果
误删恢复	删除的文件自动备份，可随时恢复
安全重启	重启服务前自动检查，异常自动回滚
脚本检测	执行脚本前自动扫描风险内容
操作留痕	所有操作自动录制，事后可回放

配置手册

快速开始 ​

工作原理 ​

下载 ​

安装 ​

Proxy ​

Agent ​

CLI ​

卸载 ​

最小配置 ​

Proxy ​

Agent ​

CLI ​

凭证来源速查 ​

CLI 配置 ​

执行模式 ​

Agent 配置 ​

Proxy 配置 ​

TLS 证书认证 ​

使用手册 ​

CLI 命令速查 ​

常用标志 ​

CLI 常用场景 ​

场景 1：执行远程命令 ​

场景 2：上传文件到 Agent ​

场景 3：从 Agent 下载文件 ​

场景 4：查看设备状态 ​

场景 5：创建和管理定时任务 ​

CLI Daemon 持久模式 ​

CLI 自更新 ​

Agent 运维与更新 ​

Agent 自更新 ​

Proxy 运维与更新 ​

Proxy 管理页面 ​

Proxy 自更新 ​

安全能力 ​

CLI 安全命令 ​

Agent 自动保护 ​

快速开始

工作原理

下载

安装

Proxy

Agent

CLI

卸载

最小配置

Proxy

Agent

CLI

凭证来源速查

CLI 配置

执行模式

Agent 配置

Proxy 配置

TLS 证书认证

使用手册

CLI 命令速查

常用标志

CLI 常用场景

场景 1：执行远程命令

场景 2：上传文件到 Agent

场景 3：从 Agent 下载文件

场景 4：查看设备状态

场景 5：创建和管理定时任务

CLI Daemon 持久模式

CLI 自更新

Agent 运维与更新

Agent 自更新

Proxy 运维与更新

Proxy 管理页面

Proxy 自更新

安全能力

CLI 安全命令

Agent 自动保护