> For the complete documentation index, see [llms.txt](https://yeasy.gitbook.io/openclaw_guide/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://yeasy.gitbook.io/openclaw_guide/di-si-bu-fen-shi-zhan-yu-you-hua-shen-du-zhi-nan/14_performance_cost/14.3_usage_budget.md).

# 14.3 OpenClaw 的用量观测与预算控制

本节介绍如何通过 OpenClaw 内置命令、Dashboard 的 `Control -> Usage` 页面实现**可刷新/近实时用量观测**，并结合 provider 控制台、外部监控或自定义插件做**预算治理**，防止成本失控。

## 14.3.1 核心观测命令

OpenClaw 提供多个内置命令用于近实时观测与诊断。若你更习惯图形化视图，当前 Dashboard 也提供 `Control -> Usage` 页面，可按时间范围查看 Token、成本与会话分布；该页面通常依赖刷新/缓存重建，短时间内可能显示 stale 或 rebuilding 状态。如果你已经在对话里通过 `/usage cost` 发现异常，再回到 Usage 页做系统级排查通常更高效。

### `/status` 命令

查看当前会话的模型、上下文、最近一次响应用量，以及在可获得价格信息时估算出的最近回复成本。它不是全局日预算报表。

```bash
/status
```

输出示例：

```
Session: main
Model: anthropic/claude-sonnet-4-6
Context: 64K / 1M
Last response: input 12,340 tokens, output 820 tokens
Estimated last-reply cost: $0.049
```

### `/usage cost` 命令

聊天会话内的本地成本摘要，适合快速看最近一段时间的费用分布。若需要 CLI 视角的 transcript-backed session 成本摘要，用 `openclaw gateway usage-cost`；`openclaw status --usage` 更适合查看 provider 配额/窗口快照，不应当成完整成本趋势报表。若需要图形化视图，可对照 Dashboard 的 `Control -> Usage` 页面。

```bash
/usage cost
```

输出示例：

```
💸 Usage cost
Session $0.049 · 13.2K tokens
Today $3.41
Last 30d $57.80
```

### `/compact` 命令

手动触发上下文压缩，回收 Token 预算。

```bash
/compact Focus on the API design decisions and unresolved tasks
```

输出：

```
压缩请求已发送；目标保留窗口请通过 agents.defaults.compaction.keepRecentTokens 调整。
```

## 14.3.2 预算配置与告警

### 全局预算限制

> \[!CAUTION] 下列配置示例反映治理架构，不等于当前 OpenClaw 已公开的 `openclaw.json` schema。生产硬阈值优先放在 provider billing / quota、外部监控或自定义插件里实现。

```json
{
  "budget": {
    "daily": {
      "tokens": 1000000,
      "cost": 500,
      "requests": 100000
    },
    "monthly": {
      "tokens": 30000000,
      "cost": 15000
    }
  },
  "alerts": {
    "enabled": true,
    "thresholds": {
      "dailyTokens": 0.8,
      "dailyCost": 0.9,
      "monthlyTokens": 0.75
    },
    "channels": ["email", "slack"]
  }
}
```

**配置解读**：

* 日预算：100 万 Token 或 $500（先达到的限制）
* 告警触发条件：日 Token 达 80%、日成本达 90%、月 Token 达 75%
* 用 `/status` 与 `/usage cost` 获取当前会话的本地成本摘要；用 `openclaw gateway usage-cost` 查看 transcript-backed CLI 成本摘要；用 `openclaw status --usage` 查看 provider 配额窗口快照。
* 用 provider 自带 quota / billing 控制台设硬预算。
* 用 Prometheus、Grafana、Loki、外部 Webhook 或自定义插件做阈值告警。

### 按 Agent 预算分配

同理，下面更适合表达“按 Agent 做预算配额”的目标，而不是当前实例已验证通过的字段名；若要落地，应由 provider 限额、入口限流、监控告警或插件 hook 执行。

```json
{
  "agents": {
    "support_agent": {
      "budget": {
        "dailyTokens": 500000,
        "dailyCost": 250,
        "enforceLimit": true
      }
    },
    "research_agent": {
      "budget": {
        "dailyTokens": 200000,
        "dailyCost": 100,
        "enforceLimit": false
      }
    }
  }
}
```

## 14.3.3 上下文管理机制

### 自动压缩与清理

```json
{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "keepRecentTokens": 5000,
        "model": "<provider/low-cost-model>",
        "truncateAfterCompaction": true,
        "maxActiveTranscriptBytes": 10485760
      }
    }
  },
  "session": {
    "maintenance": {
      "pruneAfter": "30d"
    }
  }
}
```

参数语义见字段名与本节上下文说明。

### 会话重置与清理

```bash
# 主动重置某个会话（清空上下文，开始新对话）
/new

# 批量清理过期会话
openclaw sessions cleanup --dry-run
# （使用 --dry-run 预览要删除的内容，不实际删除）

# 实际执行清理
openclaw sessions cleanup --enforce
```

## 14.3.4 成本控制的工程策略

### 策略 1：分层模型选择

当前公开配置面不提供 `routing.complexity_detection` 这种通用自动复杂度路由。更稳妥的做法是按入口、agent 或显式子任务目标拆分模型，把低成本与高质量路径变成可审计的配置：

```jsonc
{
  "agents": {
    "list": [
      {
        "id": "support_fast",
        "model": "<provider/low-cost-model>"
      },
      {
        "id": "support_deep",
        "model": "anthropic/claude-sonnet-4-6"
      }
    ]
  }
}
```

入口侧可通过 channel bindings、明确的 agent 选择或业务网关把简单请求送到 `support_fast`，把复杂分析送到 `support_deep`。这样同样能降低平均成本，同时保留可解释的路由证据。

### 策略 2：工具缓存与重复消除

当前没有通用内建 `tools.caching` 配置。对重复工具调用的缓存应放在自定义插件、业务 API 网关或外部缓存层中；同时明确排除发邮件、创建工单等有副作用工具：

```jsonc
{
  "// plugin_cache_policy": "插件内部示意，不是 OpenClaw 内建 tools.caching schema",
  "ttl": 3600,
  "keyStrategy": "hash(tool, args)",
  "excludeTools": ["send_email", "create_ticket"]
}
```

## 14.3.5 成本异常检测与预警

通过日志、会话用量与监控实现异常消费告警。下面是外部监控或插件治理的伪配置示例，不是内置 schema：

```json
{
  "anomalyDetection": {
    "enabled": true,
    "baselines": {
      "averageDailyCost": 500,
      "stdDeviation": 100
    },
    "triggers": [
      {
        "name": "spike_detection",
        "condition": "dailyCost > baseline + 3 * stdDev",
        "action": "alert + pause_non_critical"
      },
      {
        "name": "model_drift",
        "condition": "error_rate > 5%",
        "action": "notify_admin"
      }
    ]
  }
}
```

## 14.3.6 用量观测与预算控制检查清单

部署 OpenClaw 时，确保完成以下配置：

* **可见性**：运行 `/usage cost` 查看会话摘要；用 `/usage full` 或 `/usage tokens` 控制会话页脚；用 `openclaw gateway usage-cost` 查看 CLI 成本摘要；用 `openclaw status --usage` 只检查 provider 配额窗口
* **预算控制**：在 provider 控制台或外部监控里设硬阈值
* **自动压缩**：根据实际模型窗口配置 `agents.defaults.compaction`
* **会话清理**：使用 `openclaw sessions cleanup --dry-run/--enforce` 并配置 `session.maintenance.pruneAfter` / `maxEntries`
* **成本分析**：每周检查 `openclaw gateway usage-cost` 和 Dashboard Usage，并结合会话内 `/usage cost` 样本回看趋势；`status --usage` 用于补充 provider quota/window 证据
* **模型分层**：按 agent / 入口拆分模型，而不是依赖未文档化的自动复杂度路由

完成以上配置，可实现**可观、可控、可优化**的成本管理体系。