在 NemoClaw 中使用 Olares CLI Skills:让 AI Agent 通过自然语言管理 Olares 文件与应用

原创2026-10-14 18:48:431,952 阅读
文章标签:云原生后端运维

在 NemoClaw 中使用 Olares CLI Skills:让 AI Agent 通过自然语言管理 Olares 文件与应用

NemoClaw 是 NVIDIA 开源的参考技术栈,将 OpenClaw 与 NVIDIA OpenShell 运行时打包在一起,在 Olares 上构建常驻的 AI Agent。本文讲解如何通过 Olares CLI Skills 让 NemoClaw 的 Agent 用一句自然语言就能列出 Olares 上的文件、读取日志内容、安装或卸载 Market 应用——全程不需要手动敲 CLI 命令。读完本文,你将掌握完整的配置链路:在沙箱中登录 Olares CLI、从 ClawHub 安装 Olares 技能套件、触发 /reset 让 Agent 加载新技能,以及了解这些技能背后对应的 olares-cli 命令与源码实现原理。

前置条件

开始之前,请确认以下条件已满足:

  • NemoClaw 已安装并运行在 Olares 上。安装完成后,Launchpad 上会出现两个快捷方式:NemoClaw CLI(运行 NemoClaw 与 OpenClaw 命令的终端界面)和 OpenClaw Web UI(浏览器版仪表盘)。完整安装流程见 Run NemoClaw with a local LLM。
  • 你的 Olares ID 与登录密码。Olares ID 形如 laresprime@olares.com。

第一步:登录 Olares CLI

Olares CLI 的 user mode(用户模式,Olares CLI 1.12.5 起提供)以某个已登录用户的身份、通过与该用户 Web UI、LarePass 相同的 HTTP API 操作 Olares。它要求先有账户凭据,因此在使用 Olares CLI Skills 之前,需要先在 NemoClaw CLI 中完成一次登录。

1. 连接到运行时沙箱

打开 Launchpad 中的 NemoClaw CLI,连接到运行时沙箱:

nemoclaw my-assistant connect

等待终端出现沙箱提示符,例如 sandbox@my-assistant:~$。OpenClaw 以受限的非 root 环境运行,Sandbox 是该运行时提供的交互式外壳。

2. 登录 Olares 账户

执行 profile login,将 <your-olares-id> 替换为你的 Olares ID:

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

例如:

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

按提示输入 Olares 登录密码。密码输入时不回显;如果你的账户开启了双因素认证(2FA),CLI 会继续提示 two-factor code for <id>:,输入 LarePass 中的 6 位动态验证码即可。

从源码看,该命令的行为矩阵在 login.go 中有明确注释:

  • Profile 不存在 → 自动创建(可同时传入 --name 等覆盖项);
  • Profile 存在但无 token 或 token 已过期 → 复用该 profile,写入新 token;
  • Profile 存在且 token 有效 → 拒绝重复登录,并提示先用 olares-cli profile remove <id> 移除后再登录。

对于脚本化输入,可以使用 --password-stdin(从 stdin 读取一行密码)配合 --totp <code> 显式传入动态验证码——非交互式终端下启用 2FA 的账户不会出现第二次提示,需要显式传参。相关 flag 定义见 login.go:--olares-id(必填)、--name(别名,默认取 olaresId)、--password-stdin、--totp、--no-switch(登录成功后不切换当前 profile,适合脚本)等。

3. 验证登录结果

olares-cli profile list

示例输出:

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

行首的 * 标记当前选中的 profile。profile list 的语义(见 list.go)是:只依据本地 token 存储、不发起网络请求所能证明的状态:

STATUS 含义
logged-in token 存在,JWT 的 exp 仍在未来(或没有可解析的 exp,只能信任到服务端说不行)
expired token 存在,exp 已过期;下一条命令通常会先刷新再重试
invalidated token 存在但被显式标记为不可用(服务端刷新被 401/403 拒绝),优先级高于 expired
never 该 profile 没有存储任何 token
pending 平台下发的 profile,其授权尚未完成换取(通常出现在应用容器内部)
unknown 无法从本地存储或 JWT 解析出状态

登录后:token 存储与自动刷新

登录成功后,CLI 会自动保存 access/refresh token 对,并输出 token 存储后端。按平台不同(见 olares-auth.md):

OS 后端
macOS Keychain(服务 olares-cli,账户 = olaresId)
Linux Olares CLI 数据目录下的 AES-256-GCM 加密文件
Windows 当前用户注册表下的 DPAPI 加密值

之后 CLI 会透明地轮换过期的 access token:可重放的请求在认证被拒绝后自动刷新并重试一次;流式上传在 token 临近过期时会先刷新再发送数据块。因此不要自己写认证重试循环,遵循 CLI 给出的显式 profile login / profile import 提示即可。

安全要点(来自 olares-shared 的 SKILL.md):绝不把密码放进命令参数,应使用交互式提示或 --password-stdin;绝不打印 access/refresh token,导入来源应使用环境变量或密钥管理器。

第二步:从 ClawHub 安装 Olares Skills

Skills 为 Agent 增加能力(例如管理 Olares 文件与应用、集成 Google Workspace)。Olares 的 Agent Skills 是以 SKILL.md 为载体的工具定义包:Agent 收到 "列出 Olares Home 下的文件" 这类自然语言请求时,会查阅已加载的技能找到对应命令(如 olares-cli files ls drive/Home/)并代为执行。技能包源码位于仓库 cli/skills/ 目录,每个包包含一个 SKILL.md 和 references/ 参考文档。

1. 打开 Skills 页面

打开 Launchpad 中的 OpenClaw Web UI,进入 Skills 页面。

2. 搜索并安装

在 ClawHub 搜索框中输入 olares,找到 Olares 技能组:

ClawHub 中的 Olares skills

务必先安装 Olares Shared 技能——它是其他 Olares 技能的基础(“前门”)。olares-shared 的 SKILL.md 明确定义了它的职责:技能套件的路由分发、活跃 profile 模型、平台入口点,以及“认证就绪门”(auth proceed/stop rule)。cli-agent-skills.md 也强调:所有其他技能包都假定 olares-shared 已加载,它负责 profile 模型、token 刷新逻辑和认证错误恢复提示;只加载 olares-files 的 Agent 遇到认证错误时没有任何恢复路径。

然后安装其余 Olares 技能,例如:

  • Olares Files:管理 Olares 文件——上传、下载、编辑、分享、压缩解压、挂载 SMB/NFS,覆盖 drive、sync、cache、external 等命名空间(见 olares-files 的 SKILL.md);
  • Olares Market:安装、升级、卸载、克隆、停止、恢复、重启 Olares 应用,浏览目录、查看状态、上传本地 chart(见 olares-market 的 SKILL.md)。

完整技能清单(含 olares-settings、olares-cluster、olares-doctor、olares-router、olares-search 等)见 Install and use Agent Skills。

3. 重置会话让 Agent 加载新技能

打开 OpenClaw Web UI 的聊天页,执行 /reset 开启新会话,使 Agent 拾取新安装的技能。如果配置了 Discord 等频道,也需要在每个频道会话中执行 /reset。

提示:也可以在 NemoClaw CLI 沙箱中使用 openclaw config --section skills 安装技能。

注意 429 错误:下载技能时如果看到 429 错误(限流),稍等片刻重试即可。

关于技能来源的补充

如果你在本机(而非 NemoClaw 内)使用 Olares CLI,可以用 olares-cli skills install 让 CLI 把编译进二进制的技能包写到 ~/.agents/skills,并自动链接到已存在的各 Agent 技能目录(Cursor、Claude Code、Codex、OpenClaw 等)。ClawHub 上的技能副本早于技能移入二进制的时间点,不再更新,以 CLI 安装为准(见 cli-agent-skills.md)。NemoClaw 等 Olares 上的 AI Agent 应用则内置了这些技能,升级应用即可同步更新。

第三步:用自然语言与 Agent 对话

在 OpenClaw Web UI 或 OpenClaw TUI 中,直接用自然语言向 Agent 下达指令。Agent 会根据加载的技能路由到相应的 olares-cli 命令。

列出目录下的文件

要列出 /drive/Home/ 下的所有文件与文件夹:

List drive/Home/

列出文件的结果

该指令对应 olares-cli files ls drive/Home/。files 命令的路径语法是 fileType/extend<a href="https://link.gitcode.com/i/dfd914f57ca950abc7a70c882f7cc9a4" target="_blank">/subPath] 三段式(见 [olares-files 的 SKILL.md):fileType 取 drive、cache、sync、external、awss3、dropbox、google、tencent、share 之一;extend 是其内部的卷、仓库或账户名——drive/Home、drive/Data、drive/Common、节点名、Seafile 仓库 id、云账户 key 均可。因此日常 Drive 路径如 drive/Home/Documents 直接可用。

files ls 的底层实现(见 ls.go)调用 per-user files-backend 的 GET /api/resources/<fileType>/<extend><subPath>,access token 通过 X-Authorization 请求头注入;返回非 2xx 时,401/403/459 会给出统一的 run profile login 提示。表格视图每行展示 MODE / SIZE / TYPE / MODIFIED / NAME 五列,目录排在前面;追加 -o json 可输出后端原始 JSON(每个子项含 name、path、isDir、size、modified、mode、type)。

需要留意的是,Olares 平台在 drive/Home/ 第一层保留了 11 个系统管理目录(见 olares-platform.md):

Pictures  Music  Movies  Downloads  Documents  Code  Cache  Data  Home  Ollama  Huggingface

这些目录由 LarePass 创建并管理,应用依赖其精确名称;rename、rm、mv 在作为源路径时会拒绝操作这些保留名(cp 不受限,嵌套内容完全可编辑),这是平台不变量而非权限错误,遇到时改操作子路径即可。

读取文件内容

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

读取文件的结果

该指令对应 olares-cli files cat drive/Home/nemoclaw.log(管道到 tail 查看末尾)。files cat 的实现(见 cat.go)以二进制安全的方式将远端文件原始字节流式输出到 stdout,统一走 GET /api/raw/<fileType>/<extend><encSubPath>?inline=true 端点,适用于 drive / sync / cache / external 以及 awss3 / google / dropbox / tencent 所有命名空间。命令会先 Stat 路径:目标是目录时给出清晰的 “is a directory” 错误,而不是服务端晦涩的 400。cat 大图片等二进制文件会直接倾倒字节,需要安全输出时请自行管道到 less、head 等工具。

从 Market 安装应用

Install Firefox

该指令对应 olares-cli market install firefox。install 命令(见 install.go)支持一系列关键 flag:

Flag 作用
-s <source> 固定安装来源;省略时回落到自动选定的目录源(通常为 market.olares)。安装本地上传的 chart 用 -s upload
--version <ver> 指定版本(严格 semver),省略则取最新目录版本
--env KEY=VALUE 可重复,为声明了环境变量的应用赋值;缺失必填变量时后端返回结构化错误并列出具体变量
--compute-mode <type> Olares 1.12.6+ 为可在多种加速器上运行的应用(如 cpu vs nvidia)固定计算模式
--watch / --watch-timeout / --watch-interval 阻塞直到状态行稳定为 running(成功)或某个 *Failed / *Canceled(失败)。镜像拉取重的应用(Stable Diffusion、Ollama 等)常需 --watch-timeout > 15m

对 Agent 场景尤其重要的是 -o json 输出与 --watch 的组合:例如 olares-cli market install firefox --watch -o json | jq -r '.finalState' 可用于脚本化成功判定。语义上(见 olares-market 的 SKILL.md):--watch 下 .status 在状态行按本动词预期方式落定后为 success,而 .finalState 才是应用最终的落定状态——只有 install、upgrade、restart 的落定状态是 running;成功的 stop 落在 stopped、成功的 uninstall 落在 uninstalled,不要把 install 示例里的 running 检查直接套用到它们身上。另外,安装出错的常见落点是 downloadFailed 而非 installFailed——镜像 tag 不存在、仓库不可达等问题发生在拉取阶段;downloadFailed 只接受重新 install,而 installFailed 才接受 uninstall。

从 Market 卸载应用

Uninstall Firefox

该指令对应 olares-cli market uninstall firefox。与 install 不同,uninstall、stop、resume、cancel 不接受 -s 参数,它们解析用户的“我的应用”状态行而非来源(见 olares-market 的 SKILL.md)。应用处于进行中状态时,uninstall 会先 cancel 再卸载。如果拿不准应用当前是否已稳定,先执行 olares-cli market status <app> -o json 查看状态。

技能底层机制:Agent 是如何“学会”执行这些命令的

SKILL.md 即工具定义

每个 Olares Agent Skill 是 cli/skills/ 下的一个 bundle:SKILL.md 承载路由逻辑、跨领域概念和“错误到修复”矩阵;references/ 为每个非平凡子命令保存一份超过 --help 篇幅的细节文档。以 olares-files 的 SKILL.md 为例,它给出了动词索引:ls(列目录)、cat(读文件)、upload / download(传输)、edit、mkdir、rm、rename、cp / mv、chown、compress / extract / archive(压缩与归档,服务端异步任务队列)、share、smb / nfs(挂载)、repos(Seafile 同步库)等,每个动词都关联到对应的 reference 文档。

认证就绪门:proceed / stop 规则

olares-shared 的 SKILL.md 定义了技能对认证状态的处理规则,Agent 据此决定继续还是停下:

  • logged-in、expired、pending → 继续。过期的 access token 通常在下一次请求时自动刷新;pending 是平台下发 profile 的授权尚未换取的正常状态。
  • never、invalidated → 停下,执行 profile login 或 profile import——除非来源是 platform(<app>)(平台下发给应用的凭据,本地既不能签发也不能吊销,只能重装/修复该应用)。
  • unknown 或 token 不可解析 → 直接执行业务命令,根据其类型化错误响应即可。

同时明确:不要预检每条命令,CLI 对认证拒绝只自动刷新并重试一次;不要在认证错误上构建重试循环;403 权限拒绝、网络错误或 5xx 都不是登录信号。

机器可读输出约定

所有 profile 支撑的命令树统一支持 -o json 机器可读输出。失败的动词在 stderr 上返回 {"error":{"code","message","retryable","action"}}(stderr 不含其他内容,可整体解析)。值得分支处理的错误码包括 auth_no_profile、auth_not_logged_in、auth_token_expired、auth_token_invalidated、timeout 等(见 olares-shared 的 SKILL.md);其余统一为 unclassified,以 .message 为准。Market 的生命周期动词还会在结果文档中报告 .status 与 .finalState。

常见问题与排查

现象 处理
安装技能时出现 429 限流所致,稍等片刻重试
Agent 未识别新技能 在聊天页执行 /reset 开启新会话;配置了 Discord 等频道时,各频道会话也要 /reset
命令返回 401/459 或提示登录 按提示执行 olares-cli profile login --olares-id <id>(或 profile import --refresh-token);403 权限拒绝不是登录问题,重登无效
profile list 显示 invalidated / never 停止并执行 profile login / profile import
编辑 drive/Home/ 顶层目录失败 命中 11 个系统保留名,改用子路径或 cp

了解更多

登录后查看全文
Terminus