在 OpenCode 中通过 Olares CLI 让 AI Agent 用自然语言管理 Olares 设备:认证、Agent Skills 与实战指南

原创2026-10-14 19:53:071,634 阅读
文章标签:云原生后端运维

在 OpenCode 中通过 Olares CLI 让 AI Agent 用自然语言管理 Olares 设备:认证、Agent Skills 与实战指南

本文围绕 Olares 生态中 OpenCode 与 olares-cli 的集成展开:OpenCode 内置了 Olares CLI Agent Skills,使得你的编码 Agent 可以通过一句自然语言在 Olares 设备上列文件、读日志、查看系统状态,甚至从 Olares Market 安装应用。读完本文,你将掌握 olares-cli 的 Olares ID 认证流程、Agent Skills 的工作原理,以及如何指挥 OpenCode 替你完成真实的设备管理任务。

为什么 OpenCode 能"听懂"Olares 设备管理指令

OpenCode 是一款 AI 编码 Agent,能在聊天界面中运行 shell 命令、创建文件、安装开发环境。Olares 将一套 Olares CLI Agent Skills(Agent 技能包)编译进了 olares-cli 二进制,并随 OpenCode 等 Olares 上的 Agent 应用一并内置,因此 Agent 不需要人工编写脚本,就能通过自然语言调用 Olares CLI 管理设备。

从源码结构看,这套技能包位于仓库的 cli/skills/ 目录,一共 12 个套件,每个套件是一个文件夹,包含一个 SKILL.md 和若干 references/ 参考文档:

技能 用途
olares-shared 登录 Olares、管理 profile 与 token、处理认证错误,是整套技能的基石,必须最先加载
olares-files 管理 Olares 文件:上传、下载、压缩、解压、分享、挂载 SMB/NFS
olares-market 安装、升级、卸载、克隆、停止、恢复、重启 Olares 应用,浏览应用商店目录
olares-settings 修改用户、应用、VPN、网络、备份、集成、GPU、搜索等系统设置
olares-dashboard 查看 CPU、内存、磁盘、网络、Pod、GPU、风扇及应用资源排行
olares-cluster 查看 K8s 运行时状态:Pod、容器、工作负载、任务、节点、中间件,读日志、执行、扩缩容
olares-doctor 诊断应用故障:安装卡住、崩溃、镜像拉取失败、运行但不可达、变慢等
olares-router 配置与使用 AI 模型:添加云厂商模型、安装本地模型应用、签发 key 与配额、调用模型
olares-knowledge 下载任务中心:URL、yt-dlp、aria2、torrent、Hugging Face 任务的创建与暂停
olares-search 全内容搜索 Drive 文件与 Sync 库,以及按标题搜索已安装应用
olares-chart 将自有仓库、docker-compose 或 Helm chart 转化为 Olares 应用并部署
olares-publish 将本地已运行的应用发布到公开的 Olares Market

每个 SKILL.md 通过 YAML frontmatter 声明技能的名称、版本和运行时要求(要求 olares-cli 在 PATH 上、存在活动的 Olares profile)。当 Agent 收到"列出我 Olares Home 文件夹里的文件"这类请求时,它会加载 olares-files 技能,找到对应的命令(olares-cli files ls /drive/Home)并代为执行。

关键机制:所有其他技能都依赖 olares-shared 已加载——它持有 profile 模型、token 刷新逻辑和认证错误恢复提示。只加载 olares-files 而不加载 olares-shared 的 Agent,遇到认证错误时将没有任何恢复路径。这也是本文第二步之前必须完成认证的原因。

前置条件

在开始之前,请确认:

  • OpenCode 已在 Olares 上安装并运行,且已连接一个可用的模型。如果还没有完成,可先参考 Set up OpenCode as your AI coding agent 完成安装与模型连接(浏览器模式可连接本地模型如 Qwen3.8-27B,或使用 OpenAI 账户;本地 CLI 模式则需要 Router 签发的 API key)。
  • 你拥有自己的 Olares ID 和登录密码(例如 laresprime@olares.com)。

由于 OpenCode 应用随 Olares 一起内置了 Olares CLI Agent Skills,你无需手工执行 olares-cli skills install 即可使用这些技能(关于技能的手动安装与更新,参见 Install and use Agent Skills)。

第一步:用 Olares ID 认证 Olares CLI

在 OpenCode 能以你的名义运行 Olares CLI Agent Skills 之前,需要先用你的 Olares ID 完成 olares-cli 的认证。认证的本质是让 CLI 建立一个 profile(一个 profile = 一个 Olares 实例 + 一个用户身份,以 olaresId 为键),并为其保存一对访问/刷新 token。

1.1 打开 OpenCode Terminal

从 Launchpad(启动台)点击 OpenCode Terminal。它会直接打开一个命令行终端,而不是聊天界面。

1.2 确认 olares-cli 已正确安装

在终端中运行:

olares-cli -v

示例输出:

olares-cli version 1.12.6
Git commit: d30eca705df2fb614bf2bbea95daa2e6998adeeb
Build time: 2026-07-06T06:33:00Z

版本输出由 CLI 根命令的版本模板格式化(见 cli/cmd/ctl/root.go),首行保持 olares-cli version <VERSION> 的稳定格式以便脚本解析,后续行附带 Git 提交与构建时间。需要留意:如果 olares-cli 的版本早于表中所列版本,Agent 命令可能不可用,此时请升级 CLI 后再继续。

1.3 登录你的 Olares 账户

运行以下命令,将 <your-olares-id> 替换为你的真实 Olares ID:

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

示例:

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

1.4 输入密码与两步验证(2FA)

  • 当提示输入密码时,直接输入你的 Olares 登录密码。密码在输入时是隐藏的(终端回显被关闭)。
  • 如果你的 Olares 账户启用了两步验证,CLI 会提示输入该 Olares ID 对应的两步验证码:从 LarePass 中读取 6 位数字验证码,输入后按 Enter。

从源码看,这一交互流程实现在 cli/cmd/ctl/profile/login.go 与 readPassword 中:密码要么从控制终端以关闭回显的方式读取,要么通过 --password-stdin 从标准输入读取;loginWithTOTPPrompt(login.go)会在首次返回 ErrTOTPRequired 且未提供 --totp 时,在 TTY 上再提示一轮 6 位验证码并自动重试一次。因此该命令在非交互场景下还支持:

# 从 stdin 管道输入密码(适合脚本)
printf '%s' "$OLARES_PASSWORD" | olares-cli profile login --olares-id <id> --password-stdin

# 2FA 账户在脚本场景下必须显式传入 --totp
olares-cli profile login --olares-id <id> --password-stdin --totp <code>

# 登录成功后不切换当前 profile(适合自动化)
olares-cli profile login --olares-id <id> --no-switch

安全提示:不要把密码放进命令行参数中。交互式登录、--password-stdin 是官方支持的方式;TOTP 验证码是短时效的,也不应持久化到脚本或任务记录中。

1.5 验证 profile 已创建并登录

运行:

olares-cli profile list

示例输出(* 标记当前 profile):

   NAME                   OLARES-ID              STATUS     VERSION
*  laresprime@olares.com  laresprime@olares.com  logged-in  1.12.6

profile list 的实现见 cli/cmd/ctl/profile/list.go:它输出 NAME / OLARES-ID / STATUS / VERSION 四列,仅凭本地 token 存储即可判断状态,不发起网络请求。STATUS 列可能出现的取值包括:

  • logged-in:本地可用的访问 token(或 token 无可解析的过期时间)
  • expired:访问 token 已过期,下一次命令通常会自动刷新
  • invalidated:服务端已拒绝刷新授权,需要重新 profile login 或 profile import
  • never:尚未存储任何 token,需要登录或导入
  • pending:平台签发的 profile 尚未完成授权交换(应用容器内的场景)

VERSION 列是缓存的 Olares 后端版本,可通过 profile list --refresh-version 强制刷新;当存在平台签发的 profile 时,还会额外出现 SOURCE 列。

提示:这次登录会让 OpenCode 保持认证状态最长 30 天。过期之后,你需要再登录一次。这背后的机制是 CLI 的自动刷新:访问 token 到期后,CLI 会在下一个请求时透明地轮换刷新 token(olares-shared/references/olares-auth.md 中有详细说明),并且刷新是跨并发进程协调的,因此 Agent 不应自行添加认证重试循环,只需遵循 CLI 给出的显式 login/import 提示。

第二步:指挥 Agent 执行任务

认证完成后,OpenCode 中的 Agent 就能以你的身份调用 olares-cli 了。

2.1 开始一个新会话

  1. 从 Launchpad 点击 OpenCode。
  2. 新建一个会话(session),并选择你之前连接好的模型。
  3. 用自然语言向 Agent 发送请求。

2.2 从 Olares Market 安装应用

例如,让 Agent 从 Olares Market 安装 Firefox 并等待就绪:

Install Firefox from Olares Market and tell me when it is ready

这条请求在底层会触发 olares-market 技能。技能中的 Fast paths(快速路径)表会引导 Agent 使用带 --watch 的安装命令(见 olares-market/SKILL.md):

olares-cli market install firefox --watch --watch-timeout 1m -o json

然后解析输出中的 .status 与 .finalState 字段来判断安装是否已就绪。这里的细节值得注意:

  • market install 一次性的返回只代表"服务端已受理",服务端通常还会继续工作,所以 --watch 通过轮询跟踪后续状态;--watch 超时意味着"尚未到终态"而非失败(olares-market/references/olares-market-watch.md)。
  • 安装卡在 downloading 是常见且正常的——应用在拉取镜像,多 GB 镜像可能要停留数分钟。此时应耐心轮询 market status <app> --watch --watch-interval 5s,而不是把它当作失败。
  • state=running 只证明每个入口 TCP 可达,不代表应用真的健康;如果应用运行但不正常,olares-doctor 技能负责完整的健康度排查。
  • 安装所需的环境变量通过 --env KEY=VALUE 传入(可重复),例如 olares-cli market install gitea --env GITEA_TOKEN=...;需要指定 GPU 模式时(Olares 1.12.6+)可加 --compute-mode nvidia(详见 olares-market/references/olares-market-lifecycle-add.md)。

2.3 更多可交给 Agent 的任务

除了安装应用,你还可以让 Agent :

  • 管理文件:列出、读取、上传、下载、压缩、解压 Olares 上的文件。文件路径遵循 <fileType>/<extend>/<subPath> 三段式语法,如 drive/Home/、drive/Home/Documents/report.pdf、sync/<repo_id>/notes/(完整语法与各动词支持的命名空间见 olares-files/references/olares-files-paths.md)。例如:

    List the files in the Home folder on my Olares device
    

    对应底层命令 olares-cli files ls drive/Home/ -o json。其实现位于 cli/cmd/ctl/files/ls.go:CLI 调用按用户隔离的 files-backend 的 GET /api/resources/<fileType>/<extend><subPath> 接口,访问 token 由 HTTP 客户端以 X-Authorization 头注入。

  • 读取日志:通过 olares-cluster 技能查看 Pod 与容器日志。

  • 检查系统状态:通过 olares-dashboard 技能查看资源占用,例如:

    Show me which apps are using more than 1 GB of memory
    
  • 调整系统设置、管理下载任务、调用 AI 模型 等,分别对应 olares-settings、olares-knowledge、olares-router 技能。

如果 Agent 没有自动加载 Olares 技能,可以显式用斜杠(/)命令调用它们。

深入:Agent Skills 与 Olares CLI 是如何配合工作的

理解这一层机制,有助于你判断 Agent 行为的边界并排查问题。

技能包从哪来

olares-cli 的 skills 命令树(实现于 cli/cmd/ctl/skills/)负责向机器上的各 Agent 交付技能包。其中 install(install.go)会把二进制内嵌的技能套件写入 ~/.agents/skills(共享位置),并把它以相对符号链接的方式挂到机器上已存在的各 Agent 技能目录(Cursor、Claude Code、Codex、OpenClaw 等)——不会为不存在的 Agent 创建目录。技能包编译进二进制(cli/skills/embed.go),因此安装不需要访问网络,写入磁盘的必然是当前 olares-cli 二进制自带的版本,从而避免了"技能文档与命令行为版本不一致"的静默漂移。

OpenCode 与 Hermes Agent 等 Olares 上的 Agent 应用内置了这些技能:更新应用即更新技能,无需额外执行 CLI 命令。如果你是通过 npx @olares/cli@latest install 单独搭建的 CLI,技能也已一并安装好;其他安装方式则可运行:

olares-cli skills install

升级 olares-cli 之后需要重新运行一次 olares-cli skills install,让新二进制重写配套技能(顺序很重要:先升 CLI,再装技能)。在两者不一致时,skills 以外的每个命令都会在标准错误上输出一行提示,可用 OLARES_CLI_NO_SKILL_NOTICE=1 关闭。

认证门(Auth-readiness gate)与错误恢复

所有 profile 后端的技能命令都以"一个 profile 选一个 Olares 实例与一个身份"为模型(olares-shared/SKILL.md)。olares-shared 定义了认证就绪门(Auth-readiness gate):

  • logged-in、expired、pending 默认放行:过期 token 通常会在下一次请求时自动刷新。
  • never、invalidated 需要先 profile login 或 profile import。
  • 不要预检每条命令:CLI 自身会对认证拒绝做一次刷新并重试,Agent 应避免围绕认证错误构建重试循环,只有在 CLI 明确提示凭证缺失/失效或持续 401/459 时才停下来登录。

在 -o json 模式下,失败的动词会在 stderr 输出形如 {"error":{"code","message","retryable","action"}} 的结构化错误,其中 code 包括 auth_no_profile、auth_not_logged_in、auth_token_expired、auth_token_invalidated、timeout 等(olares-shared/SKILL.md),Agent 可据此分支处理。

登录的边界行为

profile login 有一套完整的行为矩阵(login.go 的注释中写明):profile 不存在则自动创建;profile 存在但 token 缺失/过期则复用 profile 写入新 token;profile 存在且 token 有效则拒绝并提示先 profile remove。也就是说,30 天到期后直接重跑 profile login 即可续期,不需要手动删除 profile。

常见问题与排查

现象 原因与处理
olares-cli -v 显示版本号低于预期 OpenCode 内置的 CLI/技能版本较旧。更新 OpenCode 应用即可同步更新内置技能;独立安装的 CLI 则先升级再重跑 olares-cli skills install
profile list 显示 expired 访问 token 过期但可刷新,正常执行下一条命令即可;若长期未使用,重跑 profile login
profile list 显示 invalidated 刷新授权已被服务端拒绝,需要重新 profile login 或 profile import
Agent 报认证错误且无恢复路径 确认 olares-shared 已随技能套件一并加载(它总是与其他技能一起写入),并按 CLI 提示重新登录
安装应用长时间停在 downloading 多 GB 镜像拉取属正常;若字节级进度完全停滞,才是拉取卡死,应交由 olares-doctor 诊断
想确认某个版本是否真的部署成功 状态行里的版本是"最后一次请求的版本",不一定是正在运行的版本;应查看工作负载上的 applications.app.bytetrade.io/version 注解(olares-cli cluster workload get <app> -n user-space-<user> --kind deployment -o json)

延伸阅读

登录后查看全文
Terminus