第 4 天教程

📎 老板视角的终极噩梦： 在模拟经营游戏里，最怕的是什么？破产。

传统的 AI 助手或早期的多 Agent 框架（如 AutoGen 或 CrewAI）中，最大的痛点之一就是 Agentic Panic（智能体恐慌/死循环）：当 AI 卡在某个问题上时，它们可能会疯狂重复调用 API，一晚上就能烧掉你几百上千美金。

但在 Paperclip AI 里，你是一个拥有上帝视角的董事会，而不是一个拿着无上限信用卡的冤大头。

本章导读

今天你将全面了解 Paperclip AI 的”财务盾牌”：

核心概念：为什么 Paperclip AI 的预算控制与众不同？
防御机制：预算控制 + 运行时保护
实战演练：通过 API 配置预算，查看成本报表

一、核心概念：独立“月薪”与支出可视化

在 Paperclip AI 中，财务管理被深度嵌入到了整个公司的操作系统（Orchestration Engine）中。

1. 每一个公司甚至每一个 Agent 都有独立的“月薪”上限

与全局限制 API Key 的消费不同，Paperclip AI 允许你为公司组织架构中的每一个 Agent（如 CEO、CTO、程序员、文案）单独设定月度预算。

2. 让你花的钱可以被看到

Paperclip AI 中，可以查看按照 Agent 或者 Project 进行花费的查看

二、防线：预算控制与运行时限制

预算控制（Budget Enforcement）

给不同的 Agent 设定符合其职级的月度预算（budgetMonthlyCents，单位是：美分）：

80% 预警：当公司级别的预算使用率达到 80% 时，Dashboard 和 Inbox 页面会显示黄色警告提示（如 “Budget at 85% utilization this month”），提醒你关注开支。
100% 自动暂停：当某个 Agent 的已花费金额 ≥ 预算上限时，系统会立刻将该 Agent 状态设为 paused。在你追加预算或等待下个自然月之前，它无法再运行。

运行时保护（Runtime Safeguards）

除了预算上限，Paperclip 还提供每次运行级别的限制，防止单次执行失控：

配置项	说明
`timeoutSec`	单次运行的最大秒数，超时则强制终止（0 = 不限制）
`graceSec`	发送中断信号后，等待多少秒再强制杀死进程（默认 15 秒）
`maxTurnsPerRun`	单次运行中 LLM 最大对话轮次（默认 300 轮）
`maxConcurrentRuns`	同一 Agent 允许同时运行的最大心跳数（默认 1）
`cooldownSec`	两次连续心跳之间的最小间隔秒数（默认 10 秒）

每次运行级别的限制

这些参数可以在 Agent 配置页面中设置，也可以通过 API 修改。它们是防止 Agent 失控的第一道物理屏障——即使预算还没花完，一次异常的运行也会被超时或轮次限制切断。

三、老板实操：通过 API 配置预算

⚠️ 注意：截至 2026-03-13 v0.3.1，Budget 的设置功能在 UI 界面上尚未完全暴露。后端功能已经完备，你需要通过 API 来配置预算。以下是完整的操作流程。

等到版本更新后，有 UI 操作了，本教程会更新

假设你正在经营一家软件开发公司，Paperclip AI 运行在 http://localhost:3100。

步骤 1：获取你的 Company ID 和 Agent ID

# 获取所有公司列表
curl http://localhost:3100/api/companies

会获得当前 Paperclip AI 上所有的公司

[
  {
    "id": "b1b65a40-a43a-4bec-bbcb-c9a2e9615cd3",
    "name": "greedisgood",
    "description": null,
    "status": "active",
    "issuePrefix": "INF",
    "issueCounter": 2,
    "budgetMonthlyCents": 0,
    "spentMonthlyCents": 407,
    "requireBoardApprovalForNewAgents": true,
    "brandColor": null,
    "createdAt": "2026-03-13T07:05:32.253Z",
    "updatedAt": "2026-03-13T09:23:33.917Z"
  }
]

这个 b1b65a40-a43a-4bec-bbcb-c9a2e9615cd3 就是 Company ID（其他字段略有不同）

# 获取某公司下的所有 Agent
curl http://localhost:3100/api/companies/b1b65a40-a43a-4bec-bbcb-c9a2e9615cd3/agents

就能获取某公司下的所有 Agent

[
  {
    "id": "4a29305c-69d6-49fd-a860-852becc851d0",
    "companyId": "b1b65a40-a43a-4bec-bbcb-c9a2e9615cd3",
    "name": "Elon",
    "role": "ceo",
    "title": "CEO",
    "icon": null,
    "status": "running",
    "reportsTo": null,
    "capabilities": "* 从 **战略层面**思考公司发展方向\n* 持续寻找 **商业化机会与盈利模式**\n* 优先考虑 **长期盈利能力和可持续增长**\n* 在做任何决策时，优先考虑 **是否能够为公司创造收入**",
    "adapterType": "claude_local",
    "adapterConfig": {
      "chrome": true,
      "graceSec": 15,
      "timeoutSec": 0,
      "maxTurnsPerRun": 300,
      "dangerouslySkipPermissions": true
    },
    "runtimeConfig": {
      "heartbeat": {
        "enabled": true,
        "cooldownSec": 60,
        "intervalSec": 3600,
        "wakeOnDemand": true,
        "maxConcurrentRuns": 4
      }
    },
    "budgetMonthlyCents": 0,
    "spentMonthlyCents": 548,
    "permissions": {
      "canCreateAgents": false
    },
    "lastHeartbeatAt": "2026-03-13T09:30:28.798Z",
    "metadata": null,
    "createdAt": "2026-03-13T07:05:44.142Z",
    "updatedAt": "2026-03-13T09:33:27.835Z",
    "urlKey": "ceo"
  }
]

其中的 4a29305c-69d6-49fd-a860-852becc851d0 就是 Agent ID

步骤 2：给公司设定月度总预算

# 设置公司月度预算为 $100（单位是美分，所以 10000 = $100）
curl -X PATCH http://localhost:3100/api/companies/{companyId}/budgets \
  -H "Content-Type: application/json" \
  -d '{"budgetMonthlyCents": 10000}'

步骤 3：给每个 Agent 发”月薪”

# CEO：月度预算 $60
curl -X PATCH http://localhost:3100/api/agents/{ceoAgentId} \
  -H "Content-Type: application/json" \
  -d '{"budgetMonthlyCents": 6000}'

# 初级程序员：月度预算 $30
curl -X PATCH http://localhost:3100/api/agents/{juniorAgentId} \
  -H "Content-Type: application/json" \
  -d '{"budgetMonthlyCents": 3000}'

💡 budgetMonthlyCents 的单位是美分。设置为 0 表示不限制预算。

步骤 4：查看成本报表

# 公司总花费概览
curl http://localhost:3100/api/companies/{companyId}/costs/summary

# 按 Agent 分拆
curl http://localhost:3100/api/companies/{companyId}/costs/by-agent

# 按项目分拆
curl http://localhost:3100/api/companies/{companyId}/costs/by-project

你也可以在 UI 的侧边栏点击 Costs 页面查看可视化报表：

cost

步骤 5：决策时刻

当 Agent 触发 80% 用量的时候，收件箱里会有提示

costWarn

追加预算并恢复：检查进度发现 Bug 快修好了，通过 API 追加预算，Agent 自动复工。

# 比如：把初级程序员的预算从 $30 追加到 $40
curl -X PATCH http://localhost:3100/api/agents/{juniorAgentId} \
  -H "Content-Type: application/json" \
  -d '{"budgetMonthlyCents": 4000}'

🔑 本章小结

Paperclip 的预算系统让你不再需要盯着 API 计费心惊胆战。预算上限控制总花费，运行时限制防止单次失控。

在这个系统里，AI 负责干活，而你，只需要做好一个老板唯一该做的事：看报表，做决策。

今日任务 ✅

通过 API 给你的公司和 Agent 配置第一笔”月薪”（budgetMonthlyCents）。
访问 Costs 页面查看当前花费。
尝试给一个 Agent 设置一个很低的预算（比如 100 美分 = $1），观察它触发自动暂停的过程。

预告：Day 5 — 实战：你的 AI 公司第一次交付

财务稳了。接下来，不再纸上谈兵——我们要让你的公司真正干一票。从设定目标到交付一个落地页，全流程实战，踩坑实录全收录。明天见。

📎 一句话总结

预算上限管住总花费，运行时限制拦住单次失控。
今天开始，你可以放心睡个安稳觉了。

Paperclip AI 教程 Day 4：成本控制——通过 API 设置 Agent 预算与运行时限制