RAAGENT 文档中心

Appearance

CLI 参考 · 安装与配对 ​

RAAGENT CLI（@raagent/raagent）运行在你的电脑上，把本机的智能体引擎接入平台。装上它并与账号配对后，你的电脑就成为一台主机，智能体真正执行在这台电脑上。

推荐以后台服务（daemon）方式运行：一次命令完成配对、注册为系统服务并启动，开机自启、崩溃自动重启，无需一直开着终端。

安装 ​

需要 Node.js 20 或更高版本。两种安装方式任选：

bash
# 方式一：全局安装（推荐）
npm install -g @raagent/raagent

# 方式二：免安装，直接用 npx 运行
npx @raagent/raagent ...

获取 API Key ​

配对需要平台 API Key：

  1. 进入个人中心 个人中心 →「我的 KEY」
  2. 新建一个 Key（raa- 开头），复制保存

Key 永久有效，同一个 Key 可以在多台主机上使用。

推荐：以 daemon 方式安装并启动 ​

一条命令完成「配对 + 安装为系统服务 + 启动」：

bash
raagent daemon install -key <你的APIKey> -dir <主机工作目录>
  • -key：你的 API Key
  • -dir：主机工作根目录——raagent 在这台电脑上允许操作的最大目录。智能体实际在哪个子目录工作，是在新建智能体时单独选择的（相对这个根目录）；每个会话则运行在 .raagent/workdir-<会话ID> 下，互不干扰

执行后终端会提示「daemon 已安装并启动」，CLI 随即作为后台服务常驻：

  • 开机自启，无需手动开启
  • 崩溃自动重启，异常退出后自动拉起
  • 平台自动适配你的系统：macOS 使用 launchd、Linux 使用 systemd、Windows 使用计划任务

首次连接自动完成

首次连接会自动创建私人助手并安装 CLI Skill。辅助初始化失败不会影响主机连接，可稍后重试。

已配对过（~/.raagent/config.json 已保存 Key 与目录）的主机，再次安装可以省略参数：

bash
raagent daemon install

daemon 日常管理 ​

bash
raagent daemon status     # 查看运行状态
raagent daemon logs -f    # 跟随日志
raagent daemon restart    # 重启
raagent daemon stop       # 停止
raagent daemon uninstall  # 卸载服务

临时前台运行（调试用） ​

如果需要临时在前台跑（例如调试），可以直接启动：

bash
# 首次：需要带 -key
raagent -key <你的APIKey> -dir <主机工作目录>

# 已配对后
raagent -dir <主机工作目录>

注意

前台方式运行在终端里，关闭终端或断开连接后主机就会离线。长期保持主机在线请使用 daemon 方式。

常用参数 ​

参数说明
-key <key>API Key（首次配对用）
-dir <dir>主机工作根目录（raagent 允许操作的最大目录）
-server <url>覆盖服务端地址（默认 https://raagent.me）
-concur <N>主机最大并发任务数，默认 10（达到上限后新任务排队）
-q安静模式
-v显示版本号
-h查看帮助

环境变量：

变量说明
RAAGENT_SERVER_URL服务端地址（同 -server）
RAAGENT_MAX_CONCUR主机最大并发任务数（同 -concur，命令行 -concur 优先）

最大并发优先级

命令行 -concur > 环境变量 RAAGENT_MAX_CONCUR > 默认 10。daemon install -concur 会把该值持久化到 ~/.raagent/config.json，后台服务重启后仍生效。-concur 必须是正整数。

配置文件与日志 ​

  • 配置：~/.raagent/config.json（保存服务端地址、Key、主机 ID、agent 目录）
  • 日志：~/.raagent/logs/raagent.log

常见问题 ​

「daemon install 缺少 -key 参数，且本地没有已保存 key」 还没有配对。请使用 raagent daemon install -key <key> -dir <dir> 完成首次安装。

「缺少 -dir 参数，且本地配置中没有 agentDir」 还没有配对。请先使用带 -key 与 -dir 的命令完成首次配对。

daemon 状态显示「已停止」 使用 raagent daemon start 启动，或 raagent daemon logs -f 查看原因。

CLI 运行了，但主机页显示离线 检查 daemon 是否在运行（raagent daemon status）；网络断开后 CLI 会自动重连。

断线后会自动重连吗？ 会。CLI 断线后按指数退避自动重连，无需手动干预。

下一步：平台命令 · 主机管理 · 引擎与运行