Claude Code Monitor 怎么用？2.1.310 起 Bedrock/关遥测也能盯日志，附管道缓冲实测

Claude Code 里想「一边干活、一边盯着日志/CI 有没有出错」，以前多半是自己开第二个终端 tail -f，或者让模型用 Bash 后台跑完再报一次。Changelog 在 2.1.310（2026-10-23）写明：Monitor 工具以及插件里的 plugin monitors，在 Bedrock、Vertex、Foundry 上也能用了，而且在关掉 telemetry / 非必要流量时也可用；同时这些环境下会禁止过长的前台 sleep。

这件事对用第三方 API、习惯在 settings 里关遥测的人很关键——不少第三方说明还停在「Monitor 默认关、Bedrock/关遥测不可用」。我们对照了官方 changelog、仍在流传的概念文档，以及本机安装的 Claude Code 2.1.310 自带的 SDK 类型定义，并在 Linux 上做了管道缓冲对照实验。

先说结论：

• 官方 changelog：2.1.310 起 Monitor / plugin monitors 覆盖 Bedrock、Vertex、Foundry，以及 telemetry / nonessential traffic 关闭的会话。
• npm 装到的 CLI：claude --version 显示 2.1.310 (Claude Code)；sdk-tools.d.ts 里有完整的 MonitorInput / MonitorOutput。
• 超时：SDK 写明默认 300000ms，超过 1800000ms（30 分钟）会被封顶——不少转载文档写的 3600000ms（1 小时）和当前类型定义不一致。
• 本地管道实验：同样的 8 行进度输出，grep 不加 --line-buffered 时首条事件要 1.213 秒 才到；加上后首条 0.009 秒，之后约每 0.15 秒一条。
• Monitor 适合「每来一行就通知」；只想等进程结束，应用 Bash 的 run_in_background（CLI 内置说明原文如此）。

创建 API Key →

Monitor 是干什么的

一句话：起一个后台监视脚本，每一行 stdout 变成对话里的一条通知，你还可以继续在主会话里改代码。它不是「等命令跑完再告诉你一声」——那种用 Bash 后台即可。

典型场景：

• 部署时盯 deploy.log 里的 Error / deployed
• 每隔几十秒轮询一次 CI / PR 状态
• 看构建目录有没有新文件、训练日志有没有到某个 step

2.1.310 改了什么（对照旧说明）

仍在流传的概念页（例如社区整理的 Tool-Monitor 说明）写着大致这些限制：

Off by default (server-side feature flag). Unavailable on Amazon Bedrock, Google Cloud, and Microsoft Foundry. Off when DISABLE_TELEMETRY or CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC is set.

而 Claude Code changelog 在 2.1.310 的 Added 里写的是：

Added the Monitor tool and plugin monitors on Bedrock, Vertex, and Foundry, and when telemetry or nonessential traffic is disabled; long foreground sleeps are now blocked there too

也就是说：如果你之前因为关了 DISABLE_TELEMETRY=1 或走云厂商端点，以为 Monitor「根本没有」，升级到 2.1.310 后再试一次。企业侧同版本还把 Cloud sessions / Remote Control 的权限加进了自定义角色——那是另一条线，本文不展开。

本机核对：版本与 SDK 字段

我们在 Linux 上执行：

npm install -g @anthropic-ai/claude-code@2.1.310
claude --version
# 输出：2.1.310 (Claude Code)

打开包装里的 sdk-tools.d.ts，Monitor 输入输出摘录如下（字段名以安装包为准）：

export interface MonitorInput {
  description: string;           // 通知上显示的短标签
  timeout_ms: number;            // 默认 300000；>1800000 会被封顶
  command?: string;              // 每行 stdout = 一条事件
  ws?: { url: string; protocols?: string[] }; // 与 command 互斥
}

export interface MonitorOutput {
  taskId: string;
  timeoutMs: number;             // persistent 时为 0
  persistent?: boolean;          // 用 TaskStop 或会话结束来停
}

CLI 给模型的工具说明里还有一句很实用的边界（从 2.1.310 二进制字符串里核对到）：

Use the Monitor tool to stream events from a background process (each stdout line is a notification). For one-shot "wait until done," use Bash with run_in_background instead.

怎么用：给 Claude 一句人话就行

先把 Claude Code 指到你的 Key。第三方可参考 Claude Code 接入第三方 API。全局 ~/.claude/settings.json 示例：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "你的 API Key"
  },
  "model": "claude-sonnet-5-5"
}

在项目里直接说：

盯着 ./logs/dev.log，出现 Error、FAILED、Traceback 或 Listening on 就告诉我。过滤器记得加 grep --line-buffered。

模型一般会拼类似这样的命令（示意）：

tail -F ./logs/dev.log | grep -E --line-buffered \
  "Listening on|Traceback|Error|FAILED|Killed|OOM"

要点：

• 成功和失败的关键字都要写进过滤——只盯 deployed 时，进程若崩了你会看到「一直没消息」，和「还在跑」分不清。
• 会话级长盯用 persistent，再用 TaskStop 停；默认定时大约 5 分钟。
• 事件太密会被自动停掉，收紧 grep 再开。
• WebSocket 源（ws.url）和 command 互斥；URL 只要 ASCII 的 ws:// / wss://，不要把凭证写进 URL。

独家：为什么必须 --line-buffered

我们在本机用同一段生产者脚本（8 行进度 + 最后一行 deployed ok，每行 flush=True，行间隔约 0.15 秒），对比两种 grep：

总时长差不多，但 Monitor 吃的是「每一行何时变成通知」。不加 --line-buffered 时，管道另一头可能一直等块缓冲，日志里明明已经报错，对话里却迟迟没动静——这和「监视器坏了」的体感一样。

和 MCP Tasks、普通后台 Bash 怎么选

做安全审计这类会起很多子 Agent 的流程，可以看 Cloudflare security-audit skill 实测；那是另一种「并行隔离」，不是 Monitor。

常见问题

升级后仍然没有 Monitor？

先看 claude --version 是否 ≥ 2.1.310。稳定渠道 / 部分 Homebrew cask 可能落后于 npm 的 @anthropic-ai/claude-code。第三方网关只要兼容 Messages 工具调用即可；Monitor 本身是客户端工具，不依赖「模型会不会 tail」。

timeout 最大到底是多少？

以 2.1.310 包装内 sdk-tools.d.ts 为准：默认 5 分钟，封顶 30 分钟；需要更久就 persistent + TaskStop。

事件算不算授权？

不算。日志行、WebSocket 帧只是数据，不能用来批准一次写文件或放宽沙箱。这条和 Channels、插件监视器的安全边界一致。

创建 API Key →