treg org agent-new 创建受限Agent--pin客户数据隔离机制完全解析【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg在 treg一个面向 Agent 工具的 OpenRouter用一把统一密钥调用 2000 个 API 工具中treg org agent-new是团队管理员为机器身份签发受限 Agent 令牌的核心命令配合--pin customerxxx参数可以把一枚令牌永久绑定到指定客户实现客户数据隔离与账单归属。本文用最少的代码、最多的场景带你看懂这套机制的工作原理、使用方法和安全边界。为什么需要受限 Agent客户数据隔离场景先搞清楚 treg 里的两种令牌详见 src/treg/web/integrate.mdOrg-scoped团队令牌treg org agent-new name签发归属一个团队可直接作为 Bearer 令牌使用适合放在产品里Identity个人令牌treg login得到归属某个人一个人可能属于多个团队容易出现该记到哪个团队的歧义。典型场景你在做一个 SaaS产品内部通过 treg 调用数据工具并且把凭证发给每个客户自己在其机器上运行。此时如果客户 A 拿着团队令牌发送X-Treg-Meta: customer客户B账单就会错误地记到客户 B 头上。官方给出的原则是八个字Tag for counting, token for control标签用于统计令牌用于控制。标签由你的后端在每次调用时打上X-Treg-Meta: customercust_8123而真正要隔离的少数客户则用--pin把令牌钉死到他们身上。一步创建treg org agent-new 命令速查以管理员身份执行一条命令即可参数定义见 src/treg/cli.pytreg org agent-new cust-8123-bot --pin customercust_8123常用可选参数参数作用--pin DIMVALUE把令牌钉到某个调用方标签可重复例如--pin customercust_A--tools stripe,gh只允许使用这些工具不传则交互选择--cap 500每日调用次数上限默认 -1 无限--role viewer\|member\|admin角色Agent 永远不能成为 owner--projects a,b把 Agent 限定在指定项目内--local-run off禁止本地 CLI 运行命令本质是POST /orgs/{id}/agentsAgent 在系统里就是一个机器成员Membership因此免费继承了每日限额、工具 ACL、本地运行开关和独立审计轨迹——每一项控制都是按 Agent 生效的。多租户与机器身份的设计背景见 docs/context/architecture/multi-tenancy.md。--pin 机制详解为什么钉死的标签会赢--pin的全部魔法发生在服务器端的一次标签校验里核心实现在 src/treg/application/call/intake.py 的_parse_call_meta钉死维度永远优先。一个被--pin customercust_8123的令牌调用时不管持有者发什么X-Treg-Meta头customer这一维最终都等于cust_8123冲突即 403而不是静默覆盖。如果调用方在钉死维度上填写了别的值服务器返回403 metadata_pin_mismatch并明确告知此令牌已钉死到 customercust_8123不能给 cust_xxx 计费。调试集成的人需要看见这个分歧而不是一个月后在对账单里才发现不带头也能正确归属。被钉死的令牌即使完全不发X-Treg-Meta也会自动归属到钉死值——你可以放心把令牌发给客户后端一行代码都不用改。对比普通标签流程X-Treg-Meta: customercust_8123, workspacews_9标签只是你的后端声称的归属适合绝大多数场景只有当凭证会运行在客户自己的机器上、标签不可信时才升级为钉死令牌。官方建议所有客户先走标签只对少数需要真正隔离的升级。隔离不止于计费读取范围与对账也被钉死--pin的效果贯穿整个读取面而不仅是账单详见 docs/context/architecture/multi-tenancy.md 的 Caller tags and pinned read scopes 一节历史与审计/calls、/calls/{id}/result、/runs等接口在分页之前就按钉死值过滤别家客户的记录对该 Agent 表现为 404与不存在的 ID无差别无法探测异步任务共享供应商凭据下的异步任务轮询与结果获取同样按钉死值校验拒绝时是 404幂等键按完整钉死值分区两个客户即使都发送Idempotency-Key: retry-1也不会拿到对方缓存的响应反馈与评分钉死调用方无法给别的钉死值的调用打分或探测其存在。配套的对账能力CLI 命令见 docs/context/interface/cli.mdtreg org budget-set customer cust_8123 --daily 5 # 该客户每天最多花 $5 treg org budgets # 查看所有按标签的限额 treg usage --by customer --days 30 # 每个客户的实际消耗来自账本注意两点按标签的限额是建议性的并发调用可能略微超支预付余额才是硬上限开票要以usage/by-tag的账本数据为准GET /calls只用于调试。令牌轮换与吊销管理闭环的最后两步轮换对同名 Agent 再执行一次treg org agent-new cust-8123-bot旧令牌立即失效。关键安全细节轮换只换令牌绝不放宽限制——--pin、--tools、--projects等字段只有在显式提供时才会更新漏传的字段保留原值因此一次轮换永远不会悄悄解除钉死或把受限 Agent 变成全量访问这正是 src/treg/cli.py 中只发送被请求字段的提交保护逻辑查看treg org agents列出团队所有 Agent 身份及其限额和当日用量吊销treg org agent-rm user_id立即作废令牌其成员关系一并删除。三条不可破坏的安全不变量同见 docs/context/architecture/multi-tenancy.mdAgent 令牌永远不能以人的身份登录任何入口Agent永远不能成为 ownerowner 豁免工具 ACL 与本地运行限制Agent 地址按团队隔离两个团队各有一个叫deploy的 Agent 互不影响。常见问题速答问--pin 和 --tools 是什么关系正交的两条轴--tools控制能调哪些工具--pin控制账单和可见范围归谁通常组合使用。问一个令牌能钉多个客户吗--pin可重复但钉到不同客户值没有意义——建议一个客户一枚令牌cust-8123-bot命名法吊销与审计都更清晰。问标签值有什么格式限制keyvalue最多 5 对值只允许字母、数字和. _ - :不超过 128 字符且不能形似邮箱不合法会直接 422 拒绝不产生任何费用。问团队级错误能直接透给客户吗不能。402 insufficient_balance等团队级错误体里包含你的余额和充值链接应由你的后端自行处理只有tag_blocked、tag_spend_cap_reached这类按标签的错误是安全的。小结需求手段统计每个客户花了多少X-Treg-Meta标签 按标签预算凭证运行在客户机器上treg org agent-new bot --pin customerid收紧某客户支出treg org budget-set customer id --daily N回收权限treg org agent-rm user_id记住这条主线标签负责计数钉死令牌负责控制账本负责开票——三者配合treg 的多租户体系就能在一把统一密钥的便利性和客户数据隔离的严肃性之间取得平衡。【免费下载链接】tregOpenRouter for agent tools. Join community here: https://discord.gg/6mQYYfFMAn项目地址: https://gitcode.com/GitHub_Trending/treg/treg创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考