企业官网建设流程全解析

• 人工智能
• AI Agent
• 大模型
• Agent 记忆
• 工具调用
• RAG
• MCP 服务
• MCP Clients

让 AI Agent 7×24 小时常驻运行，最怕的不是它不干活，而是它"干得太爽"——模型调用账单悄悄滚上天花板。Echo Agent是面向长期运行与桌面协作的开源 AI Agent，内置了完整的成本控制系统：你可以为它设置每日预算（daily_budget_usd）和软阈值（soft_threshold_ratio），当消耗逼近预算时提前预警，超支时直接硬性拦截，从根本上告别 AI 调用超支。

本指南将带你从 0 配置完这套"预算护栏"，并学会用 CLI 与 Dashboard 两个入口随时查看花费明细。

💰 为什么长期运行的 Agent 需要"预算护栏"

Echo Agent 支持多 Agent 协作、全平台接入（CLI、Telegram、微信、Webhook 等）与长期在线，任务一多、对话一长，token 消耗就会呈指数级增长。没有预算约束时，一次跑飞的自动化任务就可能烧掉你半个月的模型额度。

Echo Agent 的成本系统覆盖五个核心能力：

从架构图中可以看到，所有模型调用都经过 Agent Runtime 层，成本计量就挂载在这一层——每一次pre_LLM调用之后都会被自动记账，无需你在业务代码里加任何埋点。计量与定价的实现位于 echo_agent/cost/ 模块。

⚙️ 一键设置每日预算：只需 4 行配置

在项目的配置文件（echo-agent.yaml或config.yaml）中写入cost配置节即可启用：

cost: enabled: true daily_budget_usd: 10.0 # 每日预算（美元），0 表示不限制 soft_threshold_ratio: 0.75 # 消耗达到预算 75% 时触发软预警

四个字段的完整说明：

对应的配置结构定义在 CostConfig，配置加载器会自动把该节注入 Agent Loop。官方完整示例可参考 docs/guides/cost-control.md。

⚠️ 注意：定价覆盖表的单位是每 1M token，键名必须写成input_per_1m/output_per_1m。若误写成input_per_1k，系统不会报错，而是悄悄取默认值0.0——结果该模型费用恒为零，报表失真。

🔔 软阈值如何工作：预警一次、拦截到底

预算控制的核心是 CostTracker：它按自然日滚动累计消耗，并执行两级"闸门"。

软预警（不影响调用）当日消耗达到daily_budget_usd × soft_threshold_ratio时，系统写一条 WARNING 告警日志（每个预算周期只告警一次）。例如预算$10、阈值0.75，则在花到$7.50时提醒"该留意了"，但对话照常进行。

硬上限（直接拦截）当日消耗达到daily_budget_usd后，新的模型调用会被拒绝并抛出BudgetExceeded，错误信息会明确告知已花金额与"将于明日重置"（见 enforce）。

这个设计体现了 Echo Agent 的成本哲学：预算耗尽时停止工作，而不是静默降级到更廉价的模型——避免你在不知情的情况下得到质量下降的回答。计数按 UTC 自然日滚动重置（见 _roll_window），每日预算自动清零，无需人工干预。

📊 查看成本报告：CLI 与 Dashboard 双入口

CLI：一条命令出报表

# 查看近 7 天成本（今日按渠道 + 模型分组 + 每日趋势） echo-agent cost --days 7 # 输出 JSON 格式，适合接入监控脚本 echo-agent cost --days 30 --json

报告会展示今日按「渠道 + 模型」分组的花费明细（输入/输出 token 数、花费、合计），以及近期每日趋势柱状图。命令实现见 echo_agent/cli/cost.py，数据来源于cost_ledger_dim归因表。

Dashboard：可视化趋势与占比

Dashboard 的 Analytics 页面提供图形化成本视图：

• 📈 日/周/月成本趋势图
• 🥧 模型成本占比饼图
• 🔁 缓存命中率趋势
• 📊 预算消耗进度条

🚀 4 个省钱实战技巧

1. 模型路由：把便宜模型用在简单任务上

通过models.routes按任务类型分流，简单任务交给低价模型：

models: default_model: claude-sonnet-4-5 routes: - task_types: [simple] provider: openai model: gpt-4o-mini # 简单任务用便宜模型 - task_types: [coding] provider: anthropic model: claude-sonnet-4-5

2. 提示缓存：让重复内容少花钱

系统提示、工具定义等静态内容会被缓存，命中缓存的 token 以大幅折扣计费。通过cache_read_input_tokens指标可以监控缓存命中率，命中率越高越省钱。

3. 上下文管理：别让历史对话"吃"token

• 控制对话历史长度，避免 token 堆积
• 长期对话使用摘要而非完整历史
• 合理设置max_tokens限制输出长度

4. 本地模型免费记账

自托管模型（如 Ollama）通过pricing_overrides标价为 0，就不会污染你的 API 预算统计：

cost: pricing_overrides: ollama-llama3: input_per_1m: 0 output_per_1m: 0

定价逻辑（含 OpenAI / Anthropic 两种 usage 格式的统一归一化）实现在 echo_agent/cost/pricing.py。

✅ 快速上手清单

从这一刻起，你的 Echo Agent 就像一个会"看钱包干活"的管家：软阈值提前吹哨，硬上限果断刹车，每天定时查看echo-agent cost报表，让每一分 AI 调用预算都花在刀刃上。

📎 更多细节：docs/guides/cost-control.md · 源码模块 echo_agent/cost/ · 配置定义 CostConfig

• 人工智能
• AI Agent
• 大模型
• Agent 记忆
• 工具调用
• RAG
• MCP 服务
• MCP Clients