SwayOS 使用与开发指南

先在门户注册并验证账户，再从下载中心选择与你的系统和 CPU 架构匹配的安装包。受保护的安装包需要登录后下载。

1. 1 / ACCOUNT

   创建账户

   使用常用邮箱注册，并按邮件提示完成验证。

   注册账户 →
2. 2 / PACKAGE

   选择安装包

   确认系统、架构与版本，桌面端优先使用最新稳定版。

   查看下载 →
3. 3 / VERIFY

   启动并登录

   打开客户端，用同一账户登录；首次启动会加载可用服务。

首次运行

完成首次配置

推荐按下列顺序确认账户、设备和数据路径。这样后续安装应用或创建智能体时，系统已经有明确的执行位置。

基础概念

账户与认证

门户账户负责下载与公共服务访问；节点账户负责具体 SwayOS 环境中的资源权限。两者可能由不同服务签发凭证，不要把 Token 写进代码仓库。

核心能力

连接与管理设备

GMeta 保存设备、账户与调度等控制面信息；XAgent 运行在设备侧，承接文件、运行时和系统操作。设备出现在列表中并不等于设备侧能力已经在线。

智能体

从市场到运行

先在智能体市场确认用途、作者与版本，再安装到自己的环境。需要执行任务的智能体还必须选择在线设备和可用运行时。

1. 1

   审阅

   检查说明、版本、权限与依赖。

2. 2

   安装

   安装后回到应用中心确认入口。

3. 3

   调度

   绑定设备和运行时，再观察状态与日志。

开发工具

使用 Sway CLI

CLI 适合日常诊断、批量查询和自动化。当前仓库中的二进制名称为 sway-cli，可直接从源码安装。

cd app/sway-cli
cargo install --path . --locked
sway-cli --help

sway-cli config init
sway-cli config set gmeta_url https://<your-gmeta-host>
sway-cli auth login --username <name> --password '<password>'
sway-cli health --detailed

# List online devices as JSON
sway-cli device list --status online --format json

# Inspect the current local configuration
sway-cli config show --format human

提示：命令行密码参数可能进入 Shell 历史。共享机器上建议使用临时会话，并在完成后执行 sway-cli auth logout。

应用集成

JavaScript / TypeScript SDK

@sway/sdk 将设备、用户、应用、数据源、任务和集群等客户端集中在同一个入口。服务地址和 Token 应从部署环境注入。

import { JsSwayClient } from '@sway/sdk';

const client = JsSwayClient.new({
  gmeta_url: 'https://<your-gmeta-host>',
  auth_token: process.env.SWAY_AUTH_TOKEN,
  timeout_ms: 30_000,
});

const health = await client.healthCheck();
const devices = await client.device().listDevices();

console.log(health.status, devices.items);

配置参考

常用环境变量

自动化任务可用环境变量覆盖本地配置。机密值应来自 CI/CD 的 Secret 管理，而不是 .env 示例或仓库文件。

排查

常见问题