会话成本追踪（CostHQ）

追踪智能体（agent）会话成本、文件变更及 Git 提交。强制执行预算限制，支持本地模型（Ollama、vLLM）成本统计，并为企业用户配备完整的 Web 仪表盘与防篡改的 SOC2 合规审计日志。

最新版本：v4.0.0 — 新增语义缓存代理（Semantic Caching Proxy）与细粒度会话终止功能。

📦 npm • ⭐ GitHub • 📝 更新日志

安装

# 1. 从 npm 全局安装 CLI
npm install -g costhq

# 2. 安装 OpenClaw 技能
clawhub install costhq

安装完成后，cs 命令即可全局使用。OpenClaw 智能体将自动调用该命令进行会话追踪。

系统要求：Node.js 18+ 及 C/C++ 构建工具（用于编译嵌入式 SQLite 模块）。

操作系统	安装构建工具
Ubuntu/Debian	sudo apt-get install -y build-essential python3
macOS	xcode-select --install
Windows	npm install -g windows-build-tools 或安装 Visual Studio Build Tools
Alpine	apk add build-base python3

数据默认本地存储于 ~/.costhq/sessions.db（或 ~/.CostHQ）。

适用场景

• 始终在多步骤任务开始时启动受追踪的会话
• 始终在每次调用 AI API 后记录使用情况
• 始终在任务完成后结束会话
• 使用 cs dashboard 查看会话数据、配置本地模型，或验证审计轨迹（仅限企业版）。

命令列表

启动追踪

# 智能体模式（请始终使用 --json 获取结构化输出）：
cs start "任务描述" --json --close-stale

# 若会话异常中断（例如进程崩溃），可恢复继续：
cs start "任务描述" --json --resume

记录 AI 使用情况（每次 API 调用后执行）

# 标准云模型（成本自动计算）：
cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 8000 --completion-tokens 2000 --json

# 本地模型（含计算耗时，v3.3.0 新增）：
# --duration 支持秒数（如 120）或字符串格式（如 2m30s）；成本基于仪表盘中注册的 $/hr 单价计算。
cs log-ai -p ollama -m llama3 --tokens 4500 --duration 2m30s --local --json

# 完整字段示例：
cs log-ai -p openai -m gpt-4o --prompt-tokens 5000 --completion-tokens 1500 -c 0.04 --agent "Research Agent" --json

智能体名称：使用 --agent "Agent Name" 标识执行该操作的具体智能体。 本地模型：您可通过仪表盘注册 GPU 计算单价（$/hr），从而追踪自托管模型（Ollama、llama.cpp、vLLM 等）；记录时需同时指定 --duration 和 --local 参数。

查看当前状态

cs status --json

结束会话并获取摘要

cs end -n "完成说明" --json

结束会话将自动记录一条审计事件（企业版），并扫描 Git 仓库中的文件变更与提交记录。

Web 仪表盘

cs dashboard

仪表盘包含以下模块：

• 概览页（Overview） — 关键指标（KPI）、日趋势图、成本增速（cost velocity），以及语义缓存代理开关。
• 指令中心（Command Center） — 实时 CLI 执行监控，支持对单个会话进行细粒度终止操作。
• 会话列表（Sessions） — 支持搜索与排序的会话表格，可查看每个会话的详细信息。
• 本地模型（Local Models） — 为 Ollama、vLLM 等本地模型注册计算单价（$/hr）。
• 合规性（Compliance） — 查看防篡改的加密 SOC2 审计链（cryptographic SOC2 audit chain），并配置团队身份（Team Identities，仅限企业版）。
• 专业运维（Pro Ops） — 管理许可证、PDF 导出与同步功能。

语义缓存代理（Semantic Caching Proxy）

为节省成本，CostHQ 内置语义缓存代理，可拦截 API 请求并在请求完全相同时返回缓存响应：

cs proxy start --port 3739

也可直接通过仪表盘的 概览页（Overview） 开关启用。将您的工具配置为通过 OPENAI_BASE_URL=http://127.0.0.1:3739/openai/v1 发起请求即可。

查看历史统计与详情

cs show --json --files --commits
cs stats --json
cs export --format json --limit 10

添加备注 / 注释

cs note "测试已通过，进入清理阶段" --json

智能体工作流

智能体在执行所有命令时，必须始终附加 --json 参数，以确保输出为结构化、可解析格式。

1. 任务开始时：cs start "修复认证 Bug" --json --close-stale
2. 添加上下文备注：cs note "正在分析认证流程" --json
3. 每次 AI 调用后：cs log-ai -p anthropic -m claude-sonnet-4 --prompt-tokens 800 --completion-tokens 200 --agent "Bug Fixer" --json
4. 若使用本地模型：cs log-ai -p ollama -m mistral --tokens 1000 --duration 45s --local --json
5. 任务结束时：cs end -n "已修复认证 Bug" --json

预算与定价

• 标准模型定价可通过 cs pricing set my-model 5.00 15.00 自定义（单位：美元/百万 token）。
• 本地模型定价（基于计算时长）需在 cs dashboard 的 Local Models 页面中配置。
• 执行高成本操作前，请务必运行 cs status --json 查看当前消耗与剩余预算。

重要提示

• 务必在所有命令中使用 --json 参数 —— 智能体依赖结构化输出进行后续处理。
• 在执行 cs start 时应加上 --close-stale，以自动清理因崩溃遗留的未正常关闭会话。
• 企业模式下，系统将自动生成加密哈希链（cryptographic hash chain），完整记录会话启停、数据重置及 AI 使用行为。