远程机器使用

AxonX 可以调用另一台机器上的服务。任务在被调用服务的 Python 环境中执行，使用该服务的插件、工作区和日志目录。CLI 显式直连与 Studio 后端转发需要分别配置凭据。

准备目标服务

目标机器安装 AxonX、需要的研究插件和模型依赖，配置独立服务 token，再启动服务：

export AXONX_SERVICE_TOKEN='<目标服务 token>'
axonx start --service.host 0.0.0.0 --service.port 1024

访问目标的 HTTP(S) 地址必须对客户端可达。内置 Uvicorn 服务不负责 TLS，跨网络部署可在外部终止 HTTPS，见部署指南。

CLI 直连

export AXONX_TARGET_TOKEN='<目标服务 token>'
axonx version --target 'http://research.example:1024'
axonx get_task_definition --task demo --target 'http://research.example:1024'
axonx submit --task demo --x 1 --y 2 --target 'http://research.example:1024'

这里的域名为占位示例，需要替换。CLI 直接连接目标，不要求先启动本机 AxonX 服务，也不要求将它加入本机 targets。

当显式指定 --target 时，CLI 默认从 AXONX_TARGET_TOKEN 读取凭据；未指定时默认连接本机服务，读取 AXONX_SERVICE_TOKEN。--token 可覆盖环境来源。

等待、查状态和读日志时必须继续选择同一目标。TaskHandle 没有把远程地址变成自动路由信息，应在脚本或实验记录里同时保留目标地址。

Studio 后端转发

Studio 请求自己的同源后端，浏览器保存本机服务 token。后端根据请求中的 target 选择预先配置的远程凭据。

单个目标：内置 remote 配置

在本机启动目录的 .env 中设置：

AXONX_SERVICE_TOKEN=your-local-service-token
AXONX_TARGET=192.0.2.10:1024
AXONX_TARGET_TOKEN=your-target-service-token

替换地址和凭据，然后启动本机服务：

axonx start --config remote

内置 remote 继承 default，将上述目标地址和 token 加入 targets。在 Studio 设置本机 token，再选择远程机器。AXONX_TARGET 不会让省略 --target 的普通 CLI 命令自动改连远程；CLI 直连仍按上一节显式指定地址。

多个目标：自定义配置

使用自定义 YAML 维护多个目标或其他服务设置。下面使用 research-cluster.yaml：

extends: default
service:
  host: 127.0.0.1
  token: ${AXONX_SERVICE_TOKEN}
targets:
  - address: http://research.example:1024
    token: ${AXONX_REMOTE_RESEARCH_TOKEN}

export AXONX_SERVICE_TOKEN='<本机服务 token>'
export AXONX_REMOTE_RESEARCH_TOKEN='<目标服务 token>'
axonx start --config research-cluster.yaml

重启后在 Studio 机器入口选择目标。远程 token 留在服务端配置，浏览器不需要直接保存它。

地址会规范化，targets 不允许重复地址。转发目标未配置时会失败；UI 中能选择的目标应与本机配置一致。改配置后需要重启当前服务。

连通性与资源

axonx list_machines
axonx machine_status --target 'http://research.example:1024'

list_machines 由当前服务检查其 targets。CLI 直接查询目标的 machine_status，则在目标返回资源信息。

CPU、内存和 GPU 字段是查询时的读数，GPU 探测不可用时应查看返回字段，不能推断机器绝对没有 GPU。它们不提供资源预留、GPU 绑定或自动选机。

Studio 的 Machine resources 页面把同一类返回值展示为 CPU、内存和 GPU 卡片。下面是英文界面的资源区域截图，已去除机器地址；读数与设备数量属于截图时的示例机器，不是 AxonX 的部署要求。

远程文件和插件

本机安装的插件不会自动出现在远程。安装到目标可使用：

axonx plugin list --target 'http://research.example:1024'
axonx plugin install ./plugins/a158 --target 'http://research.example:1024'

安装后按返回的 restart_required 重启目标服务，再查询 Task 定义。远程 worker 运行该环境中的代码，source_tasks 也只定位目标工作区内目录。

需要复用本机上游产物时，应先传输需要的任务快照或按部署方式复制数据。原始数据、Agent 会话和模型环境不随远程调用迁移。

常见故障

现象	判断与处理
连接拒绝	检查目标进程、监听 host/port、网络入口
401	直连核对目标 token；Studio 同时核对本机和 targets 凭据
目标未配置	把规范化地址加入本机 targets 并重启
Task 注册名不存在	检查目标插件安装与重启，勿只查本机环境
Schema 或返回字段不同	比较双方 version 和插件版本
目标任务没有上游文件	先确认数据和 Task 目录已传到目标

鉴权 · 插件管理 · Task 同步 · 机器 API

源码：targets 模型、远程客户端、Job 路由。