如果你平时用 Claude Code 做开发大概率遇到过“限额”带来的那种尴尬需求改到一半Agent 突然开始频繁报错API 调用被限流提交不了代码只能停下来等待窗口重置。更怕的是月底看账单发现大量额度其实浪费在重复尝试、无效调用和多轮重试上。这篇文章要讲的 AgentObs就是一类专门解决“在极限到达之前提前阻止 Claude Code 继续运行”的 hook 工具。我们会从 Claude Code 的 hook 机制讲起再手把手实现一个可用的观测拦截脚本帮助你实现真正的“额度刹车”。文章适合三类读者刚接触 Claude Code、还不太清楚 hook 是什么的新手已经在使用 Claude Code、希望把成本控制在预算范围内的开发者以及准备把 Agent 工具接入团队工作流、需要统一管理额度的工程负责人。读完你不仅能理解 AgentObs 的原理还能直接复制出一套本地配额保护方案。1. 背景与核心概念1.1 从一次“超额”说起先想象一个很常见的场景你让 Claude Code 批量重构一个模块Agent 先扫描文件、再生成修改、接着又自动执行测试看起来一切正常。可由于代码量太大上下文窗口很快就吃满了Claude 开始反复压缩上下文、重试工具调用而每次重试都在消耗额度。最终代码没改完你的 API 配额倒是先见底了。这类问题的本质是Claude Code 本身并不知道你设置了“今天最多用多少次调用”或“这个项目最多花多少钱”。它只负责按你的指令执行任务至于额度消耗它并不关心。所以如果你不主动做本地保护就只能被动等待服务端限流。这就引出两个关键词一个是hook也就是 Claude Code 给外部脚本留出的“挂钩点”另一个是AgentObs一个利用 hook 机制做额度观测和拦截的工具。1.2 Claude Code 与它的“限额”问题Claude Code 是 Anthropic 推出的命令行编码代理工具你可以在终端里直接运行claude命令让它读取项目代码、调用工具、生成补丁、执行命令以对话式的方式辅助开发。只要调用 Claude 模型能力就会产生额度消耗API 调用次数限制一定时间窗口内允许的请求数量有限。Token 消耗限制按输入和输出的 token 量计费长时间、大上下文的任务消耗速度非常快。费用预算限制团队或个人会设定月度预算而 Agent 的一次错误循环可能烧掉大量预算。服务端的限流是“硬限制”它不以你的意志为转移而 AgentObs 想做的是提供一个“软限制”——还没到达服务端限制之前根据本地统计的用量数据主动停止 Claude Code 继续进行新的工具调用。1.3 什么是 AgentObsAgentObs 可以拆成 Agent 和 Obs 两部分来理解Agent 指 Claude Code 这类 AI 代理Obs 可以看作是 Observation观测或 Observer观察者。所以 AgentObs 的定位就是一个“代理观测哨兵”。它的工作方式并不复杂它作为 Claude Code 的 hook 脚本存在注册在某个生命周期事件上。每次 Claude Code 准备调用工具时hook 脚本会被触发。脚本读取本地状态文件判断当前用量是否达到阈值。如果没超限放行并累加计数如果已经超限返回退出码 2让 Claude Code 停止本次工具调用。也就是说AgentObs 不直接修改 Claude Code 的内部逻辑而是利用官方预留的 hook 机制在“本地发出请求之前”插入一个可控的检查点。它本质上是一个轻量级本地脚本没有网络代理也没有复杂的服务端依赖。2. Claude Code Hook 机制基础2.1 Hook 是什么在 Claude Code 中hook 是指在特定生命周期事件发生时由 Claude Code 自动执行的本地命令或脚本。你可以把它理解为“事件回调”当用户提交提示、Agent 打算调用工具、Agent 完成输出等时刻Claude Code 都会把当前事件的信息以 JSON 形式写到 hook 进程的标准输入然后执行你配置好的命令。hook 的典型用途包括拦截危险命令比如禁止 Agent 执行某些 bash 指令。在 Agent 操作前做提醒比如发出提示音。在工具调用后记录审计日志。在会话结束时做任务复盘。AgentObs 正是使用“工具调用前”的拦截能力配合本地计数器来实现额度控制。2.2 常用 Hook 事件Claude Code 支持的事件类型比较多我们挑几个和日常使用关系最紧密的来说事件名触发时机常见用途PreToolUse在调用任何工具之前拦截、审计、权限控制PostToolUse在工具调用完成之后记录结果、统计耗时UserPromptSubmit在用户提交新的提示消息时检查用户输入、限制会话长度NotificationClaude Code 需要用户确认时自动确认或提醒StopClaude 完成一次输出时统计会话结束SubagentStop子代理执行完成时记录子代理结果SessionStart新会话开始时初始化环境SessionEnd会话结束时清理资源PreCompact上下文压缩前保存重要状态在这些事件里AgentObs 最关注的是PreToolUse因为工具调用通常是消耗额度最快的操作点。如果你想在用户输入新消息前也做拦截那么UserPromptSubmit也可以纳入考虑。2.3 Hook 退出码的作用hook 命令执行完成后它的退出码会直接影响 Claude Code 的行为退出码 0表示放行。Claude Code 会继续执行原本的操作。退出码 2表示阻止。在 PreToolUse 事件中这个退出码会导致工具调用被取消在 UserPromptSubmit 事件中用户提示会被拦截。其它非零退出码在一些事件中会被视为异常终止具体行为因事件类型和版本不同而有所差异。这一点非常关键AgentObs 的“阻止”能力并不是靠代码逻辑强行终止 Claude Code而是通过返回退出码 2让 Claude Code 自己停止操作。2.4 配置位置Claude Code 的 hook 可以通过两份配置文件管理用户级配置~/.claude/settings.json项目级配置.claude/settings.json用户级配置对所有项目生效项目级配置只对当前项目生效通常建议提交到 Git 仓库方便团队统一管理。你可以在 settings.json 的hooks字段中按事件类型注册多个命令。下面是一个简单的例子{ hooks: { PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: echo Bash tool called } ] } ] } }matcher是工具名匹配规则支持正则表达式。上面这段配置表示当 Claude Code 准备执行Bash工具时会先运行echo命令。3. 环境准备与项目结构在开始实现 AgentObs 之前我们需要准备好运行环境。版本需要根据你的项目实际情况调整本文示例以常见环境为例重点演示配置思路。3.1 安装 Node.jsAgentObs 用 Node.js 编写主要原因是 Node.js 已经随 Claude Code 的 npm 安装链路存在而且处理 JSON 标准输入非常方便。先检查本机是否已经安装 Node.jsnode -v npm -v如果还没有安装建议使用 nvm 安装一个 LTS 版本curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash安装完成后重新打开终端执行nvm install --lts node -v3.2 安装 Claude CodeClaude Code 本身可以通过 npm 全局安装npm install -g anthropic-ai/claude-code安装完成后确认版本claude --version如果是首次使用还需要在终端中执行claude按提示完成登录认证。请注意Claude Code 的使用需要你的网络环境能够正常访问对应服务并且账号具备相应的模型访问权限。3.3 AgentObs 目录结构为了让脚本独立、好维护我建议在用户目录下单独建一个 agentobs 目录~/.claude/ ├── settings.json └── agentobs/ ├── observe.mjs ├── state.json # 脚本运行后自动生成 └── agentobs.log # 脚本运行后自动生成observe.mjsAgentObs 主程序。state.json记录当日用量。agentobs.log记录每次放行和拦截日志。目录创建命令mkdir -p ~/.claude/agentobs4. AgentObs 核心原理拆解4.1 状态文件与配额计算AgentObs 不依赖任何外部数据库它把状态保存在一个 JSON 文件里核心字段是date和used。{ date: 2025-06-01, used: 12 }date记录当前统计周期的日期。used当天已经放行的工具调用次数。每次 hook 触发时脚本先读取状态文件。如果文件里记录的日期不等于今天的日期就说明进入了新的统计周期需要把used重置为 0。这种设计的好处是即使你关掉终端、重启电脑只要系统时间还在同一天统计就不会丢失。4.2 拦截判定流程AgentObs 每次被调用都会执行下面这条判定链路从标准输入读取 hook 事件 JSON。解析出hook_event_name和tool_name等字段。读取本地state.json如果跨天则重置计数。判断used是否已经大于等于LIMIT。如果超限记录日志并返回退出码 2。如果是 PreToolUse 事件把used加 1 并写回状态文件。返回退出码 0放行当前工具调用。这个流程看起来简单但它做到了“先检查、后计数、再放行”避免出现“已经超限还多放行一次”的临界问题。4.3 为什么用“拦截工具调用”而不是“拦截 API 请求”你可能会想既然要控制额度为什么不能直接拦截 Claude Code 发出的 API 请求原因很简单Claude Code 是完整的闭源应用它并没有对外开放“请求前拦截”的 API。你无法在模型请求发出之前插入一个代理层。唯一可用的干预点就是官方 hook 机制。PreToolUse 事件发生在 Claude Code 决定调用某一个工具、但还没有真正执行工具的时候。这时候如果 hook 返回退出码 2Claude Code 就会认为工具调用被阻止从而中断当前这一轮的工具执行流程。这样原本会消耗额度的那次调用就没有机会真正发生。所以 AgentObs 采取“控制工具调用频率”的方式间接控制额度消耗。它不是精确到 token 的计费器而是一个“次数闸门”。对于大多数开发场景来说按调用次数设阈值已经足够有效。5. 完整实战在 Claude Code 中接入 AgentObs下面我们实现一份贴近 AgentObs 设计思路的参考脚本。如果你已经拿到了社区版本的 AgentObs 源码可以根据它的实际目录结构替换脚本路径如果你是从零开始这份脚本可以直接抄下来用。5.1 创建 AgentObs 主脚本创建文件~/.claude/agentobs/observe.mjs内容如下#!/usr/bin/env node /** * AgentObs - Claude Code hook * 文件路径~/.claude/agentobs/observe.mjs */ import fs from node:fs; import path from node:path; import os from node:os; const AGENTOBS_DIR path.join(os.homedir(), .claude, agentobs); const STATE_FILE path.join(AGENTOBS_DIR, state.json); const LOG_FILE path.join(AGENTOBS_DIR, agentobs.log); const DEFAULT_LIMIT 50; const LIMIT parseLimit(); function parseLimit() { const value process.env.AGENTOBS_LIMIT; if (!value) return DEFAULT_LIMIT; const num Number(value); return Number.isFinite(num) num 0 ? num : DEFAULT_LIMIT; } function ensureDir() { fs.mkdirSync(AGENTOBS_DIR, { recursive: true }); } function today() { return new Date().toISOString().slice(0, 10); } function readState() { ensureDir(); try { const state JSON.parse(fs.readFileSync(STATE_FILE, utf-8)); if (state.date ! today()) { return { date: today(), used: 0 }; } return state; } catch { return { date: today(), used: 0 }; } } function writeState(state) { ensureDir(); fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2)); } function appendLog(message) { ensureDir(); const line [${new Date().toISOString()}] ${message}\n; fs.appendFileSync(LOG_FILE, line); } function handleStatus() { const state readState(); console.log(date${state.date} used${state.used} limit${LIMIT}); process.exit(0); } function handleReset() { const state { date: today(), used: 0 }; writeState(state); console.log(reset complete); process.exit(0); } if (process.argv.includes(--status)) handleStatus(); if (process.argv.includes(--reset)) handleReset(); let raw ; try { raw fs.readFileSync(0, utf-8); } catch {} let eventName ; let toolName ; try { const parsed JSON.parse(raw); eventName parsed.hook_event_name || ; toolName parsed.tool_name || ; } catch {} const state readState(); if (state.used LIMIT) { appendLog(blocked event${eventName} tool${toolName} used${state.used}); console.error([AgentObs] blocked: 已到达今日用量上限 ${LIMIT}请明天再试或调高 AGENTOBS_LIMIT。); process.exit(2); } if (eventName PreToolUse) { state.used 1; writeState(state); appendLog(allowed event${eventName} tool${toolName} used${state.used}/${LIMIT}); console.error([AgentObs] allowed: ${toolName} (${state.used}/${LIMIT})); } process.exit(0);这段脚本包含了几个关键设计用homedir()拼接路径避免硬编码用户名。用AGENTOBS_LIMIT环境变量控制阈值默认值是 50。用date字段实现“跨天自动重置”。支持--status查看当前用量支持--reset手动清零。在超限时通过process.exit(2)阻止 Claude Code。先给脚本加上执行权限chmod x ~/.claude/agentobs/observe.mjs我们可以手动验证一下脚本的状态查询和重置功能node ~/.claude/agentobs/observe.mjs --status node ~/.claude/agentobs/observe.mjs --reset预期输出date2025-06-01 used0 limit50 reset complete5.2 配置 settings.json接下来修改~/.claude/settings.json在 hooks 字段中注册 PreToolUse 事件。{ hooks: { PreToolUse: [ { matcher: .*, hooks: [ { type: command, command: node ~/.claude/agentobs/observe.mjs } ] } ] } }配置说明PreToolUse在工具调用前触发。matcher这里填.*表示匹配任意工具名。如果你想只限制高风险工具比如只限制 Bash可以把matcher改成Bash。command要执行的命令。如果 node 不在 PATH 中建议用绝对路径比如/usr/local/bin/node ~/.claude/agentobs/observe.mjs。如果你希望 AgentObs 也能拦截“用户提交新提示”这个动作可以在 settings.json 中增加 UserPromptSubmit 事件。不过不同版本的 Claude Code 对该事件的结构支持有些差异配置前建议先查阅当前版本的官方文档。改完配置后重新启动 Claude Code 会话配置才会生效。5.3 运行验证放行场景现在我们把阈值调小方便测试。在command中临时加上环境变量{ type: command, command: AGENTOBS_LIMIT3 node ~/.claude/agentobs/observe.mjs }然后启动 Claude Codeclaude在对话中让 Claude 执行一个简单命令比如请用 Bash 运行 echo hello你会看到 Bash 工具被正常调用。此时查看日志cat ~/.claude/agentobs/agentobs.log日志里会新增一条类似这样的记录[2025-06-01T10:15:00.000Z] allowed eventPreToolUse toolBash used1/3同时查看状态node ~/.claude/agentobs/observe.mjs --status输出date2025-06-01 used1 limit3这表示第 1 次工具调用已经被记录在案。5.4 触发限流阻止场景继续在同一个会话中让 Claude Code 再执行几个工具操作直到 used 达到 3。当我们准备触发第 4 次工具调用时AgentObs 会返回退出码 2Claude Code 会中止本次工具调用。此时日志里会出现[2025-06-01T10:20:00.000Z] blocked eventPreToolUse toolBash used3在 Claude Code 的交互窗口里你会看到工具调用没有被正常执行而是返回了一条阻止提示。这条提示的具体文案取决于 Claude Code 版本的展示方式但核心含义是 hook 阻止了这次调用。如果你需要临时恢复有两种做法调高阈值把AGENTOBS_LIMIT改成更大的数字然后重启 Claude Code。手动清零在终端执行node ~/.claude/agentobs/observe.mjs --reset。注意--reset会把当前统计周期的使用次数归零生产环境使用时要谨慎避免误操作导致额度控制失效。5.5 查看运行日志AgentObs 会把每次放行和拦截都写入~/.claude/agentobs/agentobs.log。日志格式是标准的 ISO 时间加事件描述方便后续做统计[2025-06-01T10:15:00.000Z] allowed eventPreToolUse toolBash used1/3 [2025-06-01T10:16:00.000Z] allowed eventPreToolUse toolRead used2/3 [2025-06-01T10:17:00.000Z] allowed eventPreToolUse toolEdit used3/3 [2025-06-01T10:20:00.000Z] blocked eventPreToolUse toolBash used3如果日志文件没有生成优先排查目录权限和脚本执行权限。6. 常见问题与排查思路在实际使用 AgentObs 的过程中你可能会遇到下面这些问题。我把常见现象、原因和解决思路整理成一个表格方便你快速定位。问题现象常见原因解决思路hook 完全没有执行settings.json 路径不对或 JSON 格式错误检查是用户级还是项目级配置用 JSON 校验工具验证格式所有工具都被阻止AGENTOBS_LIMIT设置得太小或者 state.json 被污染执行--status查看当前计数执行--reset清零命令报node: command not foundClaude Code 进程的 PATH 中找不到 node在 command 中使用 node 绝对路径只想限制 Bash但其他工具也被限制matcher配成了.*把 matcher 改成Bash或用正则只匹配目标工具跨天计数没有自动重置系统时区和 UTC 不一致脚本使用toISOString()获取 UTC 日期如需本地日期可改用本地时间格式化修改配置后不生效没有重启 Claude Code 会话重启 claude 会话或在会话内执行配置热加载命令Windows 环境无法直接使用冒号环境变量Linux/macOS 和 Windows 环境变量语法不同在 Windows 上通过 PowerShell 设置环境变量或改用 WSL 运行 Claude Code日志文件越来越大长时间运行未清理增加日志轮转逻辑或定期归档删除其中最容易踩坑的是matcher的匹配规则。matcher是正则表达式而不是简单的通配符。.*匹配所有工具名Bash只匹配名称为 Bash 的工具Bash|Read可以匹配 Bash 和 Read 两个工具。如果你希望匹配所有以Web开头的工具可以写^Web。另外如果你在同一份配置中同时注册了多个 hookClaude Code 会按照数组顺序依次执行。前一个 hook 返回退出码 2 之后后续 hook 是否继续执行取决于当前版本的实现所以不要把关键拦截逻辑放在多个 hook 中保持一个 AgentObs 入口是最稳妥的方式。7. 最佳实践与工程建议7.1 配额模型设计按“工具调用次数”拦截只是一个起步方案。实际项目中不同工具的消耗差异很大。比如Bash工具执行一条耗时很长的命令和Read工具读取一个文件消耗的 token 完全不同。所以更合理的做法是给不同工具分配不同权重Read、Write这类轻量工具权重设为 1。Bash这类高风险、高消耗工具权重设为 3 或 5。Task子代理这类耗时不固定的工具可以单独设置上限。你可以在脚本里维护一个权重表每次放行时累加对应权重而不是简单加 1。这种做法更接近真实的成本控制。7.2 日志与审计AgentObs 的日志是审计 claude 使用情况的重要数据源。建议在日志中至少记录触发时间。事件类型。工具名称。当前计数和阈值。是放行还是拦截。如果你的团队有多人使用 Claude Code可以考虑把日志汇总到统一的日志平台。注意日志中可能包含用户的代码路径、文件名等业务信息要注意脱敏和权限控制避免敏感数据外泄。7.3 安全边界AgentObs 是一个本地脚本它的执行权限和 Claude Code 是一样的。所以在使用过程中要注意几个安全边界不要用 root 用户运行 Claude Code避免脚本被提权利用。脚本只做本地状态读写不要从网络动态拉取未知代码。修改 settings.json 前先备份避免配置错误影响其他 hook。不要把 state.json 和日志文件提交到公开仓库里面可能包含业务路径信息。还有一个容易被忽视的点hook 脚本的退出码是 Claude Code 判断是否继续执行的关键依据。如果脚本本身因为异常崩溃Claude Code 可能把它当作一次失败操作。所以建议在脚本入口处捕获所有异常保证任何情况下都能返回明确的退出码。7.4 团队推广如果你希望团队统一使用 AgentObs优先使用项目级配置.claude/settings.json把它提交到 Git 仓库。这样每个克隆项目的成员都会自动加载这套 hook。为了区分个人额度和团队额度可以通过环境变量注入{ type: command, command: AGENTOBS_LIMIT200 node ~/.claude/agentobs/observe.mjs }也可以为不同分支或不同环境准备多套配置用 CI 脚本在部署前动态生成 settings.json。要注意的是不要把个人敏感信息硬编码到配置文件中尽量使用环境变量。7.5 进阶扩展方向当 AgentObs 的基本功能稳定之后你可以往下面几个方向扩展成本估算在 PostToolUse 事件中读取 usage 信息统计每次工具调用消耗的 token 数把 state.json 从“次数计数”升级为“成本计数”。多维度限制按小时限流、按天限流、按工具分类限流可以同时生效。告警通知当用量达到阈值 80% 时通过邮件或 IM 群机器人发送提醒。历史报表基于 agentobs.log 生成周报分析哪些工具消耗最多额度。这些扩展本质上都是在 AgentObs 现有的“观测-判定-阻断”模型上增加数据源和输出端核心框架不需要大改。8. 总结与学习路线通过这篇文章我们把 AgentObs 从概念到落地拆了一遍先是理解了 Claude Code 的限额问题然后学习了 hook 机制和退出码语义接着实现了以 state.json 为核心的状态计数器最后通过 settings.json 把它接入 Claude Code 的 PreToolUse 事件。现在你应该已经能在本地部署一个最小可用的“限额刹车”系统了。如果你准备继续深入学习我的建议是按下面顺序推进先把 Claude Code 文档中 hooks 全部事件类型过一遍尤其是 PostToolUse 和 PreCompact。接着研究如何把 PostToolUse 的返回结果解析出来做 token 级别的成本统计。然后考虑把 AgentObs 的状态从一个文件升级为一个轻量级数据表方便多人共享。最后可以结合团队的实际账单周期设计一套“日配额 周配额 月配额”的分层限额策略。动手永远比看文档有效。建议你先设一个很小的阈值比如 10 次调用然后用 Claude Code 实际执行几个任务观察 AgentObs 的放行、计数、拦截行为。等熟悉了整套 hook 交互流程之后再把阈值调回正常值。这样你会对“在极限到达之前阻止 Agent”这件事建立非常直观的体感。