@scholai/openclaw-scholai-tools

OpenClaw scholai 插件的 onboarding CLI。提供 install、info、doctor、 update、self-update 命令，帮助用户在本机安装与维护 scholai channel 插件。

使用方式

无需全局安装，直接通过 npx 运行：

npx @scholai/openclaw-scholai-tools@latest install

插件包本身也暴露了一个等价入口：

npx @scholai/openclaw-scholai install

两个入口最终都会进入同一套 onboarding 流程。

命令

| 命令 | 说明 | | ------------- | ----------------------------------------------------- | | install | 在本机安装 scholai 插件并完成前置依赖配置。 | | info | 打印当前 scholai 安装的诊断信息。 | | doctor | 执行健康检查，并对常见问题给出可操作的修复建议。 | | update | 将 scholai 插件升级到最新发布版本。 | | self-update | 升级本 onboarding CLI 自身到最新版本。 |

前置依赖

• Node.js >= 22
• uv —— 运行 scholai 的 Python atoms 必备。
• openclaw CLI —— 通过 npm i -g openclaw 安装，或直接 npx openclaw。

开发

本包位于 scholai-plugins npm workspaces 中，从 repo 根目录构建与测试：

npm run build --workspace=@scholai/openclaw-scholai-tools
npm test --workspace=@scholai/openclaw-scholai-tools

Install 流程

install 按顺序执行下列阶段。每个阶段都是幂等的——重复执行命令会跳过已经 完成的工作（使用 --reset 强制重新询问凭据并重装插件）。

命令行参数

本地开发提示： 通过 npm run onboard 跑时，参数前必须加 -- 显式分隔， 否则 npm 会把 flag 吃掉而不传给底层命令。例：

npm run onboard -- --reset            # ✅ 生效
npm run onboard --reset               # ❌ 被 npm 吞掉

| 参数 | 作用 | | ----------------------- | ------------------------------------------------------------------------------- | | --version <ver> | 把插件锁定到指定 npm 版本（默认：registry 上的 latest）。 | | --reset | 强制重新询问 SCHOLAI_API_KEY 并重装插件（其他字段每次 install 都从后端拉最新）。 | | --skip-ffmpeg | 跳过 ffmpeg 自动安装（CI 或自行管理 ffmpeg 时使用）。 | | --skip-scholai-cli | 跳过 scholai-cli (Python) 安装（已手工 uv tool install -e ... 时使用）。 | | --skip-plugin-install | 跳过 openclaw plugins install 步骤（仅供 CI 冒烟测试）。 |

安装模式检测

CLI 会自动判断当前是从 monorepo 源码运行（dev 模式）还是从 npm registry 运行（registry 模式）：

• dev —— 当祖先目录中同时存在 packages/scholai-cli/pyproject.toml、 packages/openclaw-scholai/package.json、packages/openclaw-scholai-tools/package.json 时触发。scholai-cli 通过 uv tool install --force --reinstall 从本地源码安装； 插件则用现打的 npm pack tarball 安装。
• registry —— 其他情况。scholai-cli 从 PyPI 安装；插件从 npm 安装。

没有任何环境变量开关——完全基于文件系统判定。

阶段

1. Preflight —— 检查系统级依赖，缺什么就自动装什么：

   • uv（运行 scholai 的 Python atoms 必备；自动安装失败时会给出安装命令）
   • UV_TOOL_BIN_DIR / UV_TOOL_DIR 的可写性（在 atoms 安装前修复）
   • openclaw CLI（npm i -g openclaw）
   • lobster（@clawdbot/lobster）—— SKILL.md 依赖，提前装好避免 openclaw skills list 里 skill 状态显示为 "needs setup"
   • 带 libass 的 ffmpeg —— macOS 走 brew，Linux 走 apt-get / dnf / pacman 自动安装；其他平台报错并给出手装提示。 可用 --skip-ffmpeg 跳过。

2. scholai-cli (Python) —— 通过 uv tool install 安装或升级 scholai-cli。 dev 模式总是从本地源码重装；registry 模式下，本地已装版本与 PyPI latest 一致时直接跳过。可用 --skip-scholai-cli 跳过（已手工 uv tool install -e ... 时使用，前提是 scholai bin 已在 PATH 上）。

3. openclaw 插件安装 —— 对 openclaw-scholai 执行 openclaw plugins install <tarball-or-package>。registry 模式下若已装版本 与 npm latest 一致则跳过。插件先装、凭据后问，原因是：

   • 没装 skill 时 openclaw config set skills.entries.scholai.env.* 会被拒绝
   • 网络/私有镜像问题最易在这一步失败；若放到凭据之后，重试会逼用户重复输入

4. 凭据收集 —— 只 prompt 一项：SCHOLAI_API_KEY（从 https://xyls.aizixuebao.cn/settings/api-keys 控制台获取）。SCHOLAI_API_URL 默认 https://xyls.aizixuebao.cn；自托管用户可在 install 前手工 openclaw config set skills.entries.scholai.env.SCHOLAI_API_URL=<your-url> 注入，install 会沿用本地已有值。

   --reset 会强制重新询问 SCHOLAI_API_KEY；其他字段无需手输，由下一步从 后端拉取。

5. 校验 scholai key —— GET ${SCHOLAI_API_URL}/api/auth/verify 携带 x-api-key。校验失败立即终止本次 install，本地 openclaw config 不会被 修改；用户可在 ${SCHOLAI_API_URL}/settings/api-keys 创建新 key 后重跑。

6. 拉取 openclaw 配置 —— GET ${SCHOLAI_API_URL}/api/config/openclaw 携带 x-api-key，返回扁平的 Record<string, string> env map（LLM_* / VOLC_* / TENCENTCLOUD_* 等）。任何 schema 错误（非 200 / 非 object / value 非 string）都立即终止本次 install，本地 openclaw config 不会被修改。

7. 写入 openclaw config —— 纯镜像地把后端返回的 env map 写到 skills.entries.scholai.env.*：后端返回的键覆盖本地；后端返回空串 ⇒ 本地 unset；后端未返回但本地有 ⇒ 本地 unset。SCHOLAI_API_URL / SCHOLAI_API_KEY 由安装器自管（来源是用户输入），后端永远不会覆盖这两个。 然后执行 openclaw plugins enable openclaw-scholai，并把 agents.defaults.timeoutSeconds 设为 1200（用户已设置过则保持原值）。

8. 校验 config —— 最后执行 openclaw config validate 兜底，通过后报告 安装成功。

凭据存放位置

install 写入的所有内容都集中在 openclaw config 单一文件里。查看或手改：

openclaw config file        # 打印配置文件路径
openclaw config get skills.entries.scholai.env.SCHOLAI_API_URL

本工具不会读写 ~/.scholai/credentials、不会直接动 ~/.openclaw/*、也没有 任何环境变量回退路径——所有访问都经由 openclaw config 与 openclaw plugins inspect。

安装完成后

npx @scholai/openclaw-scholai-tools doctor   # 健康检查
openclaw gateway restart                     # 重启 agent
# 在 agent 对话框内：
/scholai article <url>