@meritsandtree/mt-os-cli

mt-os-cli 是 MTOS 律所管理系统的本地安装、登录、诊断和 HTTP Tool 调用工具。常规调用链路是：

Codex / Claude Code -> MTOS MCP -> 业务 tools

不走 MCP 时，也可以直接通过 CLI 调用服务端 HTTP Tool：

mt-os-cli tool list/get/call/upload -> MTOS HTTP Tool 接口

默认环境是 prod，默认服务地址是 https://law.meritsandtree.com。

安装

npm i -g @meritsandtree/mt-os-cli

本地开发仓库调试时可直接执行：

npm link /Users/june/IdeaProjects/e-mt-os-cli

自动更新

CLI 会按本地缓存轻量提醒新版本，不会在普通业务命令里静默替用户升级。真正安装新版本需要显式执行：

mt-os-cli update --check
mt-os-cli update

• mt-os-cli update --check：只检查 npm 最新版本，不执行安装，也不刷新本机 skill。
• mt-os-cli update：检测当前安装方式；如果当前命令来自 npm 全局安装且本机有 npm，会执行 npm install -g @meritsandtree/mt-os-cli@<latest>，成功后再执行 mt-os-cli skills update。
• JSON 输出会在有缓存命中新版本时附加 _notice.update，提示执行 mt-os-cli update；如需关闭提醒，可设置 MT_OS_CLI_NO_UPDATE_NOTIFIER=1。

环境预设

mt-os-cli 内置 4 套环境预设：

• local：http://localhost:8087
• dev：http://localhost:8087
• test：https://testlaw.meritsandtree.com
• prod：https://law.meritsandtree.com

默认就是 prod，因此生产环境可直接执行：

mt-os-cli auth login
mt-os-cli auth check

本地联调时先启动 law-app，再显式执行：

mt-os-cli env use local

测试环境使用前需要显式切换：

mt-os-cli env use test

常用命令

mt-os-cli env list
mt-os-cli env current
mt-os-cli env use test
mt-os-cli auth login
mt-os-cli auth login --no-wait --json
mt-os-cli auth login --device-code <device_code>
mt-os-cli auth token --env test --token <token>
mt-os-cli auth status
mt-os-cli auth check
mt-os-cli auth whoami
mt-os-cli auth refresh
mt-os-cli doctor
mt-os-cli skills
mt-os-cli skills update
mt-os-cli skill codex
mt-os-cli skill claude
mt-os-cli skill openclaw
mt-os-cli mcp
mt-os-cli mcp install
mt-os-cli mcp install openclaw
mt-os-cli tool list
mt-os-cli tool get query_customer --format json
mt-os-cli schema query_customer
mt-os-cli tool call query_customer --args-json '{}' --format json
mt-os-cli tool upload ./合同附件.pdf
mt-os-cli api GET /law/api/v1/cli/tools --query-json '{"domain":"customer"}'
mt-os-cli api GET /agent/api/v1/cli/skills

推荐使用流程

首次使用：

mt-os-cli auth login

• 登录会创建设备授权码，在终端打印二维码和授权链接，用户在浏览器里确认授权后保存本地登录态。
• 登录成功后会安装 Codex、Claude、OpenClaw 可读取的本地技能/指令，并从 /agent/api/v1/cli/skills 拉取服务端最新 skill。
• 登录不会默认写入 MCP 配置；需要 MCP 时单独执行 mt-os-cli mcp install [codex|claude|openclaw|all]。
• Agent 代用户登录时，推荐用 mt-os-cli auth login --no-wait --json，把输出里的 verification_url 原样发给用户，再用 mt-os-cli auth login --device-code <device_code> 继续轮询授权结果。
• mt-os-cli auth check 只校验 token 是否有效，token 失效会以非 0 退出码返回结构化错误。
• mt-os-cli doctor 用来检查本地 session、客户端安装状态、MCP 配置是否完整。

已安装内容

• Codex skill：~/.codex/skills/mt-os/SKILL.md
• Claude 入口指令：~/.claude/CLAUDE.md
• Claude skill：~/.claude/skills/mt-os/SKILL.md
• OpenClaw skill：~/.openclaw/skills/mt-os/SKILL.md
• 远程 MCP 服务名：mt-os
• 业务能力说明以 mt-os-cli tool list/get/schema 返回的实时 Tool 元数据为准。
• mt-os-cli schema <toolName> 返回的 parameters 就是 --args-json 可直接传的字段；outputFields 是返回 data 中重点字段，客户不需要读取服务端源码。

Tool 调用

先看服务端实时开放能力：

mt-os-cli tool list --format table
mt-os-cli tool list --domain customer --format table
mt-os-cli schema query_customer
mt-os-cli schema query_customer --format json --jq .parameters

客户侧不需要读取服务端源码。参数传递只认 schema 和 tool get 暴露的公开契约：

• parameters[].name 是 --args-json 的 JSON key，必须原样使用。
• parameters[].required=true 的字段必须传；非必填字段按场景传，不能靠源码补隐藏字段。
• 字段未出现在 schema 时，按 Tool 契约未暴露处理，需要先修服务端 Tool 定义或 skill 文档；不要读源码、历史实现或旧示例补传隐藏字段。
• 最小闭环是 tool list 找工具、schema <tool> 查参数、tool call <tool> --args-json ... 执行。

再调用具体 Tool：

mt-os-cli tool call query_customer --args-json '{"scope":"visible","page_no":1,"page_size":20}' --format json
mt-os-cli tool call create_customer --args-json '{"customer_name":"测试客户","customer_type":"机构"}' --dry-run
mt-os-cli tool call query_project_create_options --args-json '{"partner_keyword":"合伙人姓名","page_no":1,"page_size":20}' --format json

• schema 返回的 parameters[].name 就是 --args-json 的 JSON key，必须原样使用 snake_case。
• required=true 的字段必须传；未出现在 parameters 里的字段不要传。
• 没有参数的工具传 {}；文件上传使用 mt-os-cli tool upload <filePath>。
• 如果 schema 没有暴露字段，按服务端 Tool 契约缺失处理，停止调用并修契约，不要靠服务端源码、历史实现或旧示例猜参数。
• 新增项目需要用户、项目类型或办公室 id 时，先调用 query_project_create_options 获取公开选项；不要从服务端源码或旧示例猜 id。

如果命令返回 confirmation_required，需要确认参数和风险后再追加 --confirm 重试。

Raw API 调试

mt-os-cli api 用于排查 HTTP 层问题，默认只允许白名单路径前缀：

mt-os-cli api GET /law/api/v1/cli/tools --query-json '{"domain":"customer"}'
mt-os-cli api GET /agent/api/v1/cli/skills
mt-os-cli api POST /law/api/v1/cli/tools/query_customer/invoke --data-json '{"arguments":{}}' --confirm

• 允许前缀：/law/api/v1/cli/tools、/agent/api/v1/cli/skills、/user/api/v1/token/check、/user/api/v1/token/refresh、/user/api/v1/cli-device-auth。
• 非 GET 请求必须显式加 --confirm。
• 返回 HTTP 状态码、响应头和原始响应体，适合调试服务端协议差异。

Skill 更新流程

mt-os-cli skills update 默认先请求服务端 /agent/api/v1/cli/skills，把服务端动态 skill 写到 Codex、Claude 和 OpenClaw 的本机 skills 目录。只有远程不可用时，才写入 npm 包内置的 bootstrap skill 兜底。

当前 npm 包只保留非业务 bootstrap 模板：

• assets/agent-skill/SKILL.md
• assets/claude/CLAUDE.md

模板更新流程：

1. 修改 assets/agent-skill/SKILL.md 或 assets/claude/CLAUDE.md。
2. 执行 npm run typecheck && npm test && npm run build。
3. 重新执行 mt-os-cli skills update --source bundled、mt-os-cli auth login 或 mt-os-cli install codex/claude/openclaw，把 bootstrap 覆盖到用户目录。
4. 如果要对外发布，再升级 package.json 版本并发布 npm。

服务端动态 skill 更新流程：

1. 业务模块返回自己的 CliSkillFileVO 列表。
2. 部署服务端后执行 mt-os-cli skills update --source remote，只拉远程 skill。
3. 日常使用 mt-os-cli skills update 即可；远程成功时以服务端清单为准，远程不可用时写入 bootstrap 兜底。
4. CLI 会在各客户端 skills 根目录记录 .mt-os-cli-remote-skills.json，并按服务端清单清理旧文件。

MCP 测试

Codex：

mt-os-cli mcp install codex
codex exec --skip-git-repo-check "查一下我名下有多少个客户"

Claude Code：

mt-os-cli mcp install claude
claude mcp list
claude mcp get mt-os
claude -p --permission-mode bypassPermissions "查一下我参与的进行中项目，给我前5个"

OpenClaw：

mt-os-cli mcp install openclaw
openclaw mcp show mt-os --json

彻底卸载

如果你要做一次完全干净的本机复测，推荐按下面两步执行：

mt-os-cli uninstall
npm uninstall -g @meritsandtree/mt-os-cli

• mt-os-cli uninstall 会清理 Keychain 中的本地登录态、Codex/Claude/OpenClaw 的 MTOS MCP 配置、由 mt-os-cli 安装或远程下发的 mt-os、agent-*、tool-index 等技能、Claude 托管指令区块，以及 ~/.config/mt-os-cli。
• npm uninstall -g @meritsandtree/mt-os-cli 只会移除全局 mt-os-cli 命令；如果直接执行这一步，npm 不会替你清理 Keychain session 和本地配置，所以必须先执行 mt-os-cli uninstall。

诊断建议

• mt-os-cli doctor 应至少看到 session: present 和 api_check: ok。
• mt-os-cli auth check 适合 Agent 在执行业务命令前轻量校验 token；失败时按返回的 JSON 错误 hint 重新登录。
• mt-os-cli auth refresh 适合在 token 即将过期时主动刷新；如果客户端 MCP Bearer 也需要更新，再执行 mt-os-cli mcp install。