Misceo CLI 命令速查表:init、doctor、start、handoff、cost 等 8 条命令完全用法

原创2026-11-03 14:41:431,886 阅读

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

所选后端会处理下一条符合条件的请求。两个重要边界:

  1. 受保护路由和进行中的工具调用闭环优先级更高,不会被接管打断——开启 tool_use / tool_result 的后端会保持归属直到闭环完成;
  2. 接管只影响"下一条"请求,之后仍按策略路由。

决策优先级的完整顺序(显式覆盖 > 工具闭环归属 > 升级固定 > 路由规则 > 首个可见回答保护 > 手动接管 > 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。

延伸阅读

把这 8 条 Misceo CLI 命令按"装 → 查 → 跑 → 看 → 切 → 算 → 探 → 清"的顺序用熟,本地 AI 网关的日常运维就只需要这几行命令。

登录后查看全文
Misceo