在 NemoClaw 中使用 Olares CLI 技能:用自然语言管理 Olares 的文件与应用

原创2026-10-15 19:03:421,938 阅读
文章标签:云原生后端运维

在 NemoClaw 中使用 Olares CLI 技能:用自然语言管理 Olares 的文件与应用

本篇技术指南讲解如何在 NemoClaw(NVIDIA 开源的 OpenClaw 参考技术栈)中安装并使用 Olares CLI 技能,让常驻 AI Agent 通过自然语言直接管理 Olares 设备上的文件与应用。你将完整掌握 Olares CLI 的登录认证流程、ClawHub 技能安装方法,以及文件浏览、日志读取、应用安装与卸载等典型实战操作。

Olares CLI 技能是什么

Olares CLI 是一套面向 Olares 设备的命令行工具,配套的 Olares CLI 技能(Agent Skills) 以 Markdown 指令集形式封装了 CLI 的核心用法,供 OpenClaw/NemoClaw 等 Agent 框架加载。Agent 读取技能后,就能把用户的自然语言请求翻译成对应的 olares-cli 命令并执行,从而实现"说一句话,Agent 帮你操作 Olares"。

从仓库的 cli/skills 目录可以看到,这套技能以 olares- 前缀命名,按职责划分成多个独立技能包:

技能 职责
olares-shared 技能套件的基础,提供 profile/登录/auth 判定规则,其余技能的前置依赖
olares-files 文件与目录管理:ls、cat、upload、download、edit、share 等
olares-market 应用市场生命周期:install、upgrade、uninstall、restart、status 等
olares-chart Olares Chart 打包、部署与校验
olares-cluster 集群与工作负载管理(pod、job、cronjob、middleware 等)
olares-doctor 故障诊断(应用崩溃、资源不足、镜像拉取失败等)
olares-router Olares Router 调用、音频/文本/翻译等能力
olares-settings 系统设置(备份、VPN、用户、应用入口等)
olares-knowledge 知识库下载与种子管理
olares-publish 应用发布与商店 listing 管理

本指南聚焦文件与应用管理场景,因此只用到其中三个:Olares Shared(基础)、Olares Files(文件)和 Olares Market(应用)。

准备工作

开始前请确认:

  • NemoClaw 已在 Olares 上安装并运行。NemoClaw 内置 NVIDIA OpenShell 运行时,并在其中运行 OpenClaw,安装与配置过程可参考 使用本地 LLM 运行 NemoClaw。
  • 你的 Olares ID 和 登录密码。Olares ID 形如 laresprime@olares.com,是 Olares 账号体系中的唯一身份标识。

步骤 1:登录 Olares CLI

Olares CLI 需要账号密码才能访问 Olares 后端。Agent 使用 Olares CLI 技能之前,必须先让 olares-cli 处于已登录状态。这一步骤要在 NemoClaw CLI 中进行。

1.1 连接到运行时沙盒

从启动台打开 NemoClaw CLI 应用,然后连接到 Agent 的运行时沙盒:

nemoclaw my-assistant connect

等待终端显示沙盒提示符,例如 sandbox@my-assistant:~$。后续所有 olares-cli 命令都在这个沙盒 shell 中执行。

1.2 登录 Olares 账号

在沙盒 shell 中运行登录命令,将 <your-olares-id> 替换为你的 Olares ID:

olares-cli profile login --olares-id <your-olares-id>

例如:

olares-cli profile login --olares-id laresprime@olares.com

按提示输入你的 Olares 登录密码。输入时密码不回显,直接敲击键盘后按 Enter。

从源码 cli/cmd/ctl/profile/login.go 可以看到 profile login 命令的完整参数形态,几个值得注意的细节:

  • --olares-id:必填,指定 Olares ID;--name 可为 profile 指定别名(默认使用 Olares ID)。
  • --password-stdin:从 stdin 读取密码,适合脚本化输入。
  • --totp <code>:如果你的账号开启了双因素认证(2FA),需要带上一次性 TOTP 验证码。
  • --no-switch:登录成功后不切换当前 profile,适合脚本场景。

登录逻辑本身由 runLogin 实现:首次登录时自动创建 profile 并写入 token;重复对已登录 profile 运行 login 会被拒绝(需要先 olares-cli profile remove <id> 再重新登录)。密码读取使用 term.ReadPassword 关闭终端回显,且全程不会打印或记录密码(cli/cmd/ctl/profile/login.go)。登录成功后,CLI 还会"尽力而为"地预取用户角色与后端版本缓存,供后续 settings、gpu 等版本感知命令使用。

1.3 检查 profile 登录状态

olares-cli profile list

示例输出:

NAME                   OLARES-ID              STATUS
*  laresprime@olares.com  laresprime@olares.com   logged-in (23h59m)

行首的 * 表示当前选中的 profile。STATUS 列是理解认证状态的关键。结合 cli/cmd/ctl/profile/list.go 的 profileStatus 实现,各状态含义如下:

状态 含义 应对方式
logged-in 本地 token 可用(JWT 未过期,或无 exp 声明) 直接继续
expired token 已过期 可继续,下一次请求通常会自动刷新
invalidated 服务端拒绝了 refresh grant,整个凭证失效 停止,重新 profile login 或 profile import
never 尚未存储任何 token 停止,先执行 profile login
pending 平台签发的 profile 尚未完成授权交换 可继续,下次命令会自动交换

源码中 profile list 输出的头部实际还包含 VERSION 列(缓存的后端版本号,可用 --refresh-version 刷新),并在存在平台签发 profile 时追加 SOURCE 列。agent 技能中关于登录的判定规则详见 cli/skills/olares-shared/references/olares-auth.md,其中强调:不要把密码放进命令行参数,优先使用交互式输入或 --password-stdin;token 存储在不同平台上分别使用 macOS Keychain、Linux AES-256-GCM 加密文件、Windows DPAPI。

步骤 2:从 ClawHub 安装 Olares 技能

Olares CLI 技能通过 ClawHub(OpenClaw 的包管理器)分发。NemoClaw 的 OpenClaw 默认未预装这套技能,需要手动安装。

  1. 打开 OpenClaw Web UI,进入 Skills 页面。
  2. 在 ClawHub 搜索框中输入 olares,找到 Olares 技能。

ClawHub 中搜索到的 Olares 技能列表

  1. 先安装 Olares Shared 技能。它是其他 Olares 技能的基础,定义了 profile 模型、认证判定规则与技能路由,其他技能(如 Files、Market)都依赖它。
  2. 再安装其余 Olares 技能,例如 Olares Files 和 Olares Market。
  3. 安装完成后,打开 OpenClaw Web UI 的聊天页面,运行 /reset 开启新会话,让 Agent 重新加载并识别新安装的技能。如果你已配置 Discord 等频道,也需要在每个频道会话中运行 /reset。

遇到 429 错误时重试:如果下载技能时看到 429 错误,说明触发了限流,稍等片刻后重试即可。

技能安装的更多方式

除了 ClawHub 图形化安装,NemoClaw 沙盒内还支持命令行方式安装技能:

openclaw config --section skills

该向导可引导安装默认或官方支持的技能并补齐缺失依赖。你也可以在沙盒中用 ClawHub CLI 直接搜索与安装:

openclaw skills list
openclaw skills search olares
openclaw skills install <skill-id>

关于技能加载机制(工作区技能 > 托管/本地技能 > 捆绑技能的优先级)、技能被阻止的常见原因(操作系统不兼容、缺少 bins 可执行文件、缺少配置或环境变量)以及缺失依赖的安装方法,详见 管理技能和插件。

步骤 3:用自然语言与 Agent 对话

安装并 /reset 之后,打开 OpenClaw Web UI 或 OpenClaw TUI,即可用自然语言向 Agent 提出请求。下面逐个演示本指南覆盖的典型场景。

列出目录下的文件与文件夹

List drive/Home/

Agent 会将其翻译为 olares-cli files ls drive/Home/ 并执行。以下截图展示了实际会话结果:

Agent 列出 drive/Home 目录的会话结果

这里使用的 files ls 是 cli/skills/olares-files/SKILL.md 中定义的规范发现命令。从 cli/skills/olares-files/references/olares-files-ls.md 可以了解到它的输出形态:默认表格为 MODE SIZE TYPE MODIFIED NAME,目录排在文件之前且目录名带 / 后缀;-o json 则输出后端原始 envelope,便于脚本解析。

Olares 文件路径采用 fileType/extend/subPath 三段式语法(cli/skills/olares-files/references/olares-files-paths.md):

段 含义
fileType 存储类别:drive、cache、sync、external、awss3、dropbox、google、tencent、share、internal
extend 卷/仓库/账号。Drive 下必须是 Home、Data 或 Common(大小写敏感);Sync 为 Seafile 仓库 id;云盘为账号 key
subPath extend 内的路径,前导 / 隐式存在

示例:drive/Home/、drive/Home/Documents/report.pdf、drive/Common/huggingface/、sync/<repo_id>/notes/。注意路径末尾的 / 具有语义:drive/Home/Foo/ 表示目录意图,drive/Home/Foo 表示文件意图。drive/Home 下第一层还有 11 个系统托管的保留目录名,rm、rename、mv 等操作会被拒绝,需要操作其子项而不是保留目录本身。

读取文件内容

Read the last 10 lines of the nemoclaw.log file in the Home directory.

Agent 会调用 files cat 相关能力读取文件字节。以下截图展示了读取文件的会话结果:

Agent 读取 nemoclaw.log 的会话结果

技能文档特别提醒:对文件资源直接做原始 GET 可能返回 HTTP 500,应始终使用 files cat 或 files download,而不要重试原始资源 URL。对于上传、编辑、压缩解压、SMB/NFS 挂载、Seafile 同步等更复杂的文件操作,Olares Files 技能提供了完整的 verb 索引(upload、download、edit、compress、extract、share、smb、nfs、repos 等),均可通过自然语言触发。

从应用市场安装应用

Install Firefox

Agent 会调用 olares-cli market install firefox。从 cli/cmd/ctl/market/install.go 的源码可以看到该命令的完整能力:默认安装目录源 market.olares 的最新版本,可用 --version 指定版本、--env KEY=VALUE 注入环境变量、--compute-mode 指定计算模式(如 nvidia,Olares 1.12.6+)、--watch 阻塞等待安装完成并输出最终状态。技能文档建议使用:

olares-cli market install <app> --watch --watch-timeout 1m -o json

通过读取 .status 判断安装结果。需要注意的是:--watch 的超时只表示"尚未到达终态"而非失败;安装常见的失败状态是 downloadFailed(镜像 tag 不存在、仓库不可达等镜像拉取问题),它只能通过重新 install 清除,而 installFailed 则接受 uninstall。

从应用市场卸载应用

Uninstall Firefox

Agent 会调用 olares-cli market uninstall firefox。结合 cli/skills/olares-market/SKILL.md 的说明,uninstall 属于应用生命周期"移除"类操作:当应用处于中途状态(mid-flight)时它会先执行 cancel;成功的 uninstall 最终落在 uninstalled 状态。市场相关的常用命令还包括 market list --mine(查看已装应用)、market status <app>(跟踪单个应用生命周期)、market upgrade、market stop、market resume 等。

常见问题与安全注意事项

技能没有生效

安装技能后 Agent 无法识别新能力,通常是因为会话仍是旧上下文。在 OpenClaw Web UI(以及每个已配置的频道会话)中运行 /reset 开启新会话即可。

认证相关问题

  • 登录后状态为 expired:无需担心,CLI 会在下一次请求时透明地自动刷新 access token(刷新在 goroutine 与并发 CLI 进程间协调,Agent 不应自行增加认证重试循环)。

  • 状态为 invalidated 或 never:需要重新执行 profile login 或 profile import。profile import 使用已有的 refresh token 引导:

    olares-cli profile import --olares-id <olares-id> --refresh-token "$OLARES_REFRESH_TOKEN"
    

    token 应从环境变量或密钥管理器中读取,绝不要粘贴到命令行字面量中。

  • 2FA 账号:交互式登录会在输入密码后提示输入 6 位验证码;脚本化场景则需显式传 --totp <code>。

安全准则

  • 绝不要把密码放在命令参数里,优先使用交互式提示或 --password-stdin。
  • 绝不打印 access token 或 refresh token。
  • 涉及登录、凭证替换、目标模糊或超出授权范围的操作,Agent 应先向用户确认。

了解更多

登录后查看全文
Terminus