Fleet：身份、权限、审批与 Workspace 治理

Fleet 的治理不是一个开关，而是 Agent 分享权限、Agent 身份/凭据、工具 RBAC/ABAC、内置集成 workspace gate、工具审批、trace 审计、secret 与预算的组合。任何单层都不能替代其余层。

Agent identity 是不可逆设计决定

创建后设置的 Agent identity 当前不能修改，需要变更时只能新建 Agent。两种模式：

身份模型	官方别名	凭据来源	适合	主要风险
Fixed credentials	Claws	始终使用 Agent owner 连接的一套 API key/OAuth token	团队 Slack bot、共享资源、channels、schedules	所有人以同一主体操作，权限放大，审计需额外关联调用人
User credentials	Assistants	每个调用者首次连接自己的账户，以其 token 操作	私人邮件、按用户权限访问数据	每位用户要授权；跨用户行为与后台触发受限

Channels 和 schedules 要求 fixed credentials，因为无人触发时没有可用的最终用户 OAuth 上下文。固定身份应使用专用 service account、最小权限、可轮换凭据，避免绑定个人离职账户。

Agent 分享不是线程共享

Agent 可以 private、workspace-wide 或分享给特定人。权限维度包含：

Clone：复制并形成自己的可编辑副本；
Run：使用但不能改配置；
Edit：修改 instructions、tools 与 settings。

可把 Edit 给核心团队、Run 给组织、Clone 给需要二次定制的人。工作区 Agent 的 system prompt、工具选择、sub-agents 与 channel 类型对工作区用户可见；具体 OAuth connection 和 channel 实例不共享。线程始终 user-scoped，即使 Agent 是 workspace scope，聊天历史也只属于创建该 thread 的用户。

这意味着：共享 Agent 配置不会自动授予原 owner 的私人 OAuth 连接；但 workspace secrets 是 workspace-scoped，private 与 workspace Agent 都可能使用它们，因此 secret 的权限面要单独治理。

工具访问的三层策略

企业版工具控制覆盖 custom MCP server 与内置 integrations。

RBAC

mcp-servers:* 权限：

权限	能力
`read`	发现和列出 MCP servers/integrations
`invoke`	调用工具，含 OAuth connect/disconnect
`create`	新建 MCP server 配置
`update`	修改 server 配置
`delete`	删除 server 配置

read + invoke 会让角色看见并使用 workspace 中全部 MCP servers 和 integrations，不能误以为它天然是细粒度授权。

ABAC

ABAC 可按 tag 对 mcp_server 与 fleet_integration 资源做 allow/deny。它既能给无通用 RBAC 权限的角色只开放某些标签资源，也能从有广泛 RBAC 权限的角色中排除高风险资源。

Workspace integration policy

内置 integrations 还有 workspace 管理员控制的全局启停 gate。禁用后任何 RBAC/ABAC 都不能重新开放；该页面需要 workspaces:manage。

精确求值顺序

flowchart LR
    A["内置集成 Workspace gate"] --> B["ABAC deny"]
    B --> C["RBAC"]
    C --> D["ABAC allow 补充授权"]

Custom MCP 不经过第一步，顺序是 ABAC deny → RBAC → ABAC allow。Deny 永远优先；内置集成若 workspace gate 关闭，后续完全不评估。生产排障应按这个顺序查，不能只看角色权限。

人工审批与 auth interrupt 是不同机制

工具在 Connections 中可设：

Auto：直接执行；
Ask：执行前暂停，用户 Accept 或 Reject 并可给修正意见。

Fleet 有跨 Agent 的中央 approvals inbox，Slack trigger 也可在原 thread 中 Approve/Deny。审批能降低副作用风险，但不是权限系统：一个本来无权调用工具的人不能靠批准绕过 RBAC/ABAC；一个拥有权限的 Agent 也不能因为有审批就忽略输入校验、幂等和审计。

自定义工具需要 OAuth 时，可以只返回以下 JSON 字符串：

{
  "auth_required": true,
  "auth_url": "https://auth.example.com/start",
  "auth_id": "opaque-tracking-id"
}

Fleet middleware 识别后暂停、显示授权 UI，成功后自动重试同一个 tool call。输出必须只有这段 JSON，不要附加说明文字；auth_id 可用于关联授权会话。自动重试要求工具设计幂等，尤其当“是否已完成副作用”与“授权失败”边界不清时。

Secret 治理

Fleet 默认使用 LangChain 托管模型，不需要 provider key。自定义模型或特定工具才从 workspace secrets 读取：

FLEET_ 前缀优先于通用 secret，例如 FLEET_OPENAI_API_KEY 会覆盖 OPENAI_API_KEY；
Exa 需要 EXA_API_KEY；Tavily 需要 TAVILY_API_KEY；
X 读取需要 TWITTER_API_KEY 与 TWITTER_API_KEY_SECRET，文档说明 posting/media upload 未开放；
Remote MCP 的 headers 也在 workspace 配置中，并会用于 discovery 与 invoke。

Secret 名称必须与 provider 期望的环境变量一致。不要把 key 写进 instructions、memory、tool output 或 trace；使用最小权限 secret、分环境 workspace、轮换计划和访问审计。

预算与执行边界

Usage 页面需要 fleet:read-admin-config；设限需要 fleet:write-admin-config。可查看 7/14 天 spend、threads、runs，并按 Agent 或用户分解；默认每 Agent/用户周限额可被个别 override，星期一重置。

预算限制有三个容易误判的边界：

变更需要数分钟传播；
只在 run 开始时检查，已开始的 run 即使最终超限仍会完成；
成本以 traces 计算，删除 trace 会影响报表与 enforcement。

因此预算不是实时熔断器。高成本工具和递归 Agent 仍需限制 recursion、单 run token/时间、并发、外部 API 配额，并对接近限额告警。

管理操作与不可逆风险

model、connections、sharing、memory approval 和 channels 可在侧栏调整；
Download ZIP 导出完整 Agent 配置；View code snippets 给出程序化调用入口；
Pause Agent 实际是 pause all channels，UI chat/API 能力需另行确认，不能当全面停机开关；
Delete Agent 不可恢复，会永久删除 Agent、关联 threads，并解除 attached channels；删除前先导出、停触发、盘点外部调用与保留要求。

默认 memory write 需要批准。Schedule/其他自动触发若会写 memory，应在确认风险后把 “Update memory and instructions” 改为 Auto，否则会一直等待；同时要限制 Agent 可写目录、对 memory diff 建立审计与恢复点。

审计与生产基线

Fleet actions 会进入结构化 LangSmith trace，含工具调用、决策与输出。结合 identity 和权限，目标是能回答：哪个 Agent、代表谁、使用哪类凭据、在什么输入下、调用什么工具、产生什么结果。

生产基线：

身份模型在设计评审时确定；固定身份使用专用账户，用户身份验证跨用户隔离。
默认 private + 只读 tools + Ask；通过评估后逐项开放共享、写权限和 Auto。
以 workspace gate 做禁用基线，ABAC deny 隔离高风险资源，RBAC 给常规角色，ABAC allow 做窄例外。
共享前检查 prompt、tools、sub-agents、channel 类型是否包含内部信息。
Secret 按环境与用途拆分；Fleet-specific key 用于成本归因，不与其他 LangSmith 工作负载混用。
对授权失败、审批拒绝、重复事件、token 过期、预算传播延迟与删除操作做演练。
Trace 保留与删除策略要和费用统计、调查取证、隐私要求一起设计。