Misceo CLI 命令速查表:init、doctor、start、handoff、cost 等 8 条命令完全用法
Misceo CLI 命令速查表:init、doctor、start、handoff、cost 等 8 条命令完全用法
Misceo 是一个在本地运行、兼容 Anthropic API 的 AI 网关:它把符合条件的请求先交给低成本模型,检查候选答案后,再在策略要求时升级到强模型。本文是 Misceo CLI 命令速查表,一次讲清 init、doctor、start、status、handoff、cost、audit、logs 这 8 条命令的完整用法,帮助新手从初始化到成本核算全流程走通。
先看懂全局:8 条命令速查表
安装(npm install --global @misceo/cli)完成后,所有日常操作都围绕以下 8 条命令展开:
| 命令 | 一句话用途 | 何时用 |
|---|---|---|
misceo init |
创建私有的起始 .env 配置 |
第一次部署 |
misceo doctor |
静态检查配置是否正确 | 配置后、启动前 |
misceo start |
启动代理与内嵌管理界面 | 每次使用 |
misceo status |
查看当前路由与会话状态 | 验证流量是否经过网关 |
misceo handoff |
手动切换活动后端 | 临时指定某后端处理请求 |
misceo cost |
报告 token 成本与可计算的节省 | 每周复盘开销 |
misceo audit |
显式执行会产生费用的兼容性探测 | 切换服务商/协议时 |
misceo logs |
清理、重建索引或删除本地历史 | 日志占空间或需重建索引时 |
💡 这 8 条命令覆盖了"装 → 查 → 跑 → 看 → 切 → 算 → 探 → 清"的完整生命周期,记牢这张表基本就够用。
misceo init:一键创建私有 .env 配置
misceo init 会生成一份简洁的 .env 起始配置,并在系统支持时自动设置私有文件权限。除非明确加上 --force,否则它会拒绝覆盖已有文件——这是防止误删密钥的保险设计。
mkdir my-misceo
cd my-misceo
misceo init --mode balanced
三个可选预设对应不同的成本与质量策略:
| 参数 | 策略含义 |
|---|---|
--mode quality-first |
必须配置评审模型,评审不可用时直接升级 |
--mode balanced |
配置评审时使用,是默认模式 |
--mode savings-first |
跳过评审模型,最大化节省 |
📌 小贴士:需要把环境文件写到其他目录时,使用 --output PATH 参数。完整的变量说明见 docs/configuration.zh-CN.md。
misceo doctor:启动前的静态配置体检
创建 .env、填入服务商密钥后,先跑一次 doctor 再启动:
misceo doctor
它会检查运行时、配置结构、必需凭据是否存在、端点格式、监听安全和价格覆盖。两点必须知道:
- ⚠️
doctor只做静态检查:不会连接服务商、不验证实时凭据、不证明模型当前可用; - 缺少价格的警告不会阻止启动,但配置错误会阻止启动。
如果 doctor 提示缺少某个密钥,说明该后端被默认路由、规则、cascade 或评审模型使用,把提示中的变量补进 .env 即可。详见 docs/troubleshooting.zh-CN.md。
misceo start:启动代理与管理界面
misceo start
该命令以前台方式运行,并输出两个本地地址:
- 代理端点:
http://127.0.0.1:4141(客户端把ANTHROPIC_BASE_URL指向这里) - 管理界面:
http://127.0.0.1:5141(实时流量、历史、成本)
保持终端打开,按 Ctrl+C 可正常停止并刷新当前流量日志。常用监听参数:
misceo start --port 4242 # 更换代理端口
misceo start --ui-port 5242 # 更换管理界面端口
misceo start --ui-host 127.0.0.1
misceo start --no-ui # 只跑代理,关闭界面
⚠️ 端口被占用时,换端口的同时要记得同步修改客户端的 ANTHROPIC_BASE_URL。管理界面没有用户登录功能,除非前方有可信认证,否则请始终保持 loopback 监听,详见 docs/dashboard.zh-CN.md。
misceo status:确认路由与当前会话
misceo status
用于查看当前路由状态、活动会话和手动切换状态。验证客户端是否真的走 Misceo 时,推荐"组合拳":
curl http://127.0.0.1:4141/healthz
misceo status
注意:healthz 健康响应只能证明本地监听已启动;新增的流量记录 + status 中的会话状态,才能证明客户端确实经过 Misceo 而不是绕过它直连服务商。
misceo handoff:手动切换活动后端
misceo handoff zai
misceo handoff anthropic
所选后端会处理下一条符合条件的请求。两个重要边界:
- 受保护路由和进行中的工具调用闭环优先级更高,不会被接管打断——开启
tool_use/tool_result的后端会保持归属直到闭环完成; - 接管只影响"下一条"请求,之后仍按策略路由。
决策优先级的完整顺序(显式覆盖 > 工具闭环归属 > 升级固定 > 路由规则 > 首个可见回答保护 > 手动接管 > cascade > 默认后端)见 docs/routing-and-handoff.zh-CN.md。
misceo cost:核算 token 成本与节省
misceo cost
misceo cost --since 7 # 只看最近 7 天
misceo cost --json # 输出 JSON,便于脚本处理
cost 会区分返回给客户端的答案、被丢弃的低成本尝试、中断的流式请求、评审调用,以及在全强模型基线下的节省金额。
⚠️ 只想看 token 没有金额?那是价格没配全。需要为所有参与后端(包括首次尝试、升级和评审后端)配置当前价格,例如:
MISCEO_ANTHROPIC_PRICING={"inputPerMTok":3,"outputPerMTok":15}
MISCEO_ZAI_PRICING={"inputPerMTok":0.6,"outputPerMTok":2.2}
缺失的用量或价格会被明确报告,Misceo 不会静默估算。价格相关变量见 docs/configuration.zh-CN.md。
misceo audit:显式的付费兼容性探测
misceo audit
audit 会真实调用已配置的后端,验证端点、协议和模型标识是否可用。注意它与 doctor 的本质区别:
| 命令 | 是否产生费用 | 检查什么 |
|---|---|---|
doctor |
否 | 静态配置结构 |
audit |
是 | 实际请求连通性与兼容性 |
在切换服务商、修改 MISCEO_ZAI_BASE_URL 或 MISCEO_ZAI_PROTOCOL 之后,跑一次 audit 能直接确认端到端可用。
misceo logs:清理、重建索引与删除历史
流量日志是保存在配置目录中的 append-only JSONL 文件,可能包含提示词与回答,因此 logs 子命令是数据管理的关键:
# 1. 重建本地搜索索引(旧会话不显示时用它)
misceo logs reindex
# 2. 按天数和大小清理,先预览再执行
misceo logs prune --dry-run --max-days 30 --max-bytes 2GB
misceo logs prune --max-days 30 --max-bytes 2GB
# 3. 删除单个会话(需先停止代理进程)
misceo logs forget CONVERSATION_ID
三条注意事项:
- 🔒
forget删除不可恢复;管理界面也可以删除单个会话或全部历史; - 保留策略(
MISCEO_LOG_MAX_DAYS/MISCEO_LOG_MAX_BYTES)需要主动配置才生效; - 卸载 npm 包不会删除
.env或本地日志,需单独归档或删除。
数据流向与保留策略的完整说明见 docs/privacy-and-data.zh-CN.md。
推荐组合:把 8 条命令串成日常流程
🚀 首次部署
misceo init --mode balanced # 建配置
misceo doctor # 静态体检
misceo start # 启动
🔎 验证与运维
misceo status # 看路由与会话
misceo cost --since 7 # 周度成本复盘
misceo logs reindex # 索引异常时重建
🔀 临时调整
misceo handoff anthropic # 临时切强后端
misceo audit # 改动端点后付费探测
常见问题快答
Q:配置改完没生效?
配置只在启动时加载,停止后重新 misceo start 即可。
Q:管理界面返回 403 Forbidden?
使用 127.0.0.1 或 localhost 访问;自定义主机名需加入 MISCEO_UI_ALLOWED_HOSTS 并重启。
Q:上游请求 404?
检查端点与协议组合:Anthropic 协议 base URL 通常不含 /v1;OpenAI 协议网关通常保留 /v1 并设置 MISCEO_ZAI_PROTOCOL=openai。
更多安装、端口、历史类问题见 docs/troubleshooting.zh-CN.md。
延伸阅读
- docs/getting-started.zh-CN.md:安装、配置、连接、验证、升级与卸载
- docs/configuration.zh-CN.md:环境变量、端点、价格与监听地址
- docs/routing-and-handoff.zh-CN.md:Cascade 决策、会话身份与工具闭环
- README.zh-CN.md:产品总览与 CLI 快速索引
- CHANGELOG.zh-CN.md:版本变更(
init与doctor于 0.1.1 新增)
把这 8 条 Misceo CLI 命令按"装 → 查 → 跑 → 看 → 切 → 算 → 探 → 清"的顺序用熟,本地 AI 网关的日常运维就只需要这几行命令。