XClawLink

快速开始

工作原理

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

组件	功能定位	最小必要配置
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

unzip xclawlink-proxy-v1.0.0-Beta-linux-amd64.zip
cd xclawlink-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

unzip xclawlink-agent-v1.0.0-Beta-linux-amd64.zip
cd xclawlink-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

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

Windows（用管理员权限打开 PowerShell）

bash

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

卸载

bash

# Linux
sudo bash uninstall.sh

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

最小配置

编辑对应配置文件，填入必需的凭证参数：

Proxy — /opt/xclawlink/proxy/config.yaml

relay.token — JWT 令牌，从 Portal → Tokens 获取
relay.tenant_id — 租户 ID，从 Portal 获取

Agent — /opt/xclawlink/agent/config.yaml

proxy.host — Proxy 服务器 IP/域名（自动派生 url 和 kcp 地址）
proxy.device_id — Agent 设备 ID，从 Proxy 管理页面获取
security.otp — Agent OTP，从 Proxy 管理页面获取
security.tenant_id — 租户 ID，从 Portal 获取

CLI — /opt/xclawlink/cli/config.yaml

auth.token — JWT 令牌，从 Portal → Tokens 获取
auth.tenant_id — 租户 ID，从 Portal 获取
auth.otp — 目标 Agent 的 OTP，从 Proxy 管理页面获取
cli.device_id — CLI 设备标识，从 Portal → Devices → Create CLI 获取

凭证来源速查

配置项	组件	从哪里获取
`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 证书。

配置手册

快速开始 ​

工作原理 ​

下载 ​

安装 ​

Proxy ​

Agent ​

CLI ​

卸载 ​

最小配置 ​

凭证来源速查 ​

CLI 配置 ​

执行模式 ​

Agent 配置 ​

Proxy 配置 ​

TLS 证书认证 ​

快速开始

工作原理

下载

安装

Proxy

Agent

CLI

卸载

最小配置

凭证来源速查

CLI 配置

执行模式

Agent 配置

Proxy 配置

TLS 证书认证