OpenClaw学习总结_IV_认证与安全_4：Multi-Account Patterns详解

OpenClaw IV. 认证与安全4Multi-Account Patterns本篇目标把“一个人/一个团队同时拥有多个账号或多个 Bot / 多个 Workspace / 多个 Provider credentials”时OpenClaw 侧应该怎么建模、怎么隔离、怎么切换、怎么审计说清楚。适用读者在同一套 OpenClaw 部署里接入多个机器人账号/多个工作区Slack/Feishu 等/多个环境staging prod/多租户 SaaS且希望做到“不串线、可追责、可控回退”。你会学到多账号在 OpenClaw 里通常对应哪些“对象”accountId / channel / identity / session / workspace4 类最常见模式单人多号、团队多号、环境多号、多租户怎么落地账号选择/切换策略显式/隐式、默认账号、回退账号安全边界与最小权限token 存储、scope、数据隔离、审计字段常见坑账号串线、跨号读 memory、误把 admin 号当默认、回调混淆等1. 为什么 Multi-Account 是“认证与安全”问题增量说明2026-03-08本节新增“生产级强隔离落地蓝图”第 14 节把多账号从概念讲解推进到可直接复制的配置模板 入口分流 sessionKey 编码 memory namespace 审计 schema 熔断/回滚清单。很多系统把多账号当成“易用性需求”能登录多个账号、随时切换。在 OpenClaw 里多账号首先是安全问题因为它天然引入权限边界变多不同账号的 token scope 不同允许的动作不同。数据面变复杂不同账号对应不同 DM、不同群、不同 workspace、不同联系人目录。审计与追责变难同一句话/同一次工具调用到底是哪个账号执行的回调与状态容易串webhook 回来时必须能精确映射到“哪个账号实例”。所以本篇用“安全工程”的方式处理多账号先建模哪些实体必须唯一、哪些可以共享再给切换机制如何选择执行账号最后定义隔离与审计哪些数据绝对不能跨2. OpenClaw 里与“账号”相关的核心对象不同 channel/provider 的叫法不同Telegram bot、Slack app、Feishu tenant…但在 OpenClaw 侧建议统一成下面几个概念。2.1 accountId执行身份accountId是最关键的抽象代表“一套可执行动作的凭据集合”绑定到一个或多个 channel connector例如Telegram bot token、Slack bot token、Feishu app credentials在工具层面很多工具都支持accountId参数或通过 session 选择用来明确指定“用哪个账号发/查”。经验规则只要凭据不同就应该是不同 accountId。如果只是同一凭据的不同展示昵称/头像不需要拆。2.2 channel消息入口channel 是“消息从哪里来/要发到哪里去”。多账号往往意味着同一种 channel如 Slack下多个 bot/app同时接入多种 channelSlack Telegram Feishu注意channel ! accountId。channel 是类型/路径accountId 是在该 channel 下的一套具体凭据2.3 identity对端用户/群的身份身份映射需要考虑同一个人可能在不同平台有不同 id同一平台内在不同 workspace/tenant 内 id 也可能不同因此 identity 的主键通常是(channel, tenant/workspace, userId)并且 identity 绝对不应该在不同 tenant/workspace 间“合并”除非你有明确的跨租户绑定流程。2.4 session对话状态容器session 是 agent loop 的工作单元。关键原则session 必须绑定一个确定的 accountId执行身份同时绑定一个“对端 identity / chatId / threadId”等路由信息否则会遇到典型事故A 账号收到的消息却用 B 账号去回复在同一个 session 中混入两套 token导致权限不一致、审计不可追2.5 workspace / memory namespace数据隔离域OpenClaw 的 memory / files 是最容易“串线”的地方。多账号系统里建议把 memory 的命名空间至少分层tenant/workspace组织/空间accountId执行身份conversation/session会话最小可行方案按 accountId 切 memory 根目录例如memory/accountId/...更成熟方案memory/tenant/accountId/conversationKey.md3. 四种最常见 Multi-Account 模式模式 A单人多号个人主号 小号 / 工作号需求同一个人希望用“主号”处理日常事务用“工作号”处理公司群/客户或者主号绑定个人支付/敏感权限小号用于低风险自动化典型风险默认账号选错把高权限号当默认memory 串线把工作群对话写进个人 session 的长期记忆建议落地账号选择明确让用户指定默认账号/account default work且默认账号一定是低权限sessionKey 编码 accountIdchannel:tenant:accountId:chatIdmemory namespace至少按 accountId 拆模式 B团队多号多个 bot / 多个 workspace需求同一套 OpenClaw 服务同时为多个团队/多个 workspace 服务各团队希望自己的 bot 只访问自己的数据典型风险“共享存储/共享缓存”导致跨团队泄漏webhook 回调混淆同一路径接所有团队建议落地ingress 分流路径或子域携带ingressKey做到一眼定位 account强制 tenantId所有 trace/audit 必填 tenantIdstorage 硬过滤任何查询必须携带 tenantId/accountId 过滤条件否则 fail-closed模式 C环境多号staging/prod 分离需求staging 用测试 botprod 用生产 bot希望同一套代码/配置体系支持切换典型风险staging token 写进 prod 配置prod 会话误用 staging 的工具/模型建议落地env 作为一级分区env必须进入 sessionKey / trace / namespace禁止跨 env fallbackprod 不允许 fallback 到 staging反之可允许release gate上线前跑“入口唯一性 session 绑定一致性 namespace 隔离”合约测试模式 D多租户 SaaSTenant-based需求一个 OpenClaw SaaS 给很多客户tenant用每个 tenant 都有自己的一套 channel credentials 或 workspace典型风险tenant 识别错误导致“误把 A 的消息当成 B”共享模型/工具导致的权限穿透建议落地tenantId 从 ingress 决定不可来自用户输入任何高风险工具要求 explicit delegation需要租户侧审批合约测试随机抽样多 tenant 入口验证不可能映射到同一 account4. 账号选择与切换显式 vs 隐式4.1 显式选择推荐显式选择指用户或系统在请求中明确指定要用哪个 accountId。命令式/use accountworkUI选择器APIaccountId字段优点可审计、可解释、可 fail-closed。4.2 隐式选择谨慎使用隐式选择常见策略根据入口ingressKey/webhook path根据 chatId/workspaceId 映射根据 session 绑定隐式选择必须满足决策过程可追责写入 audit决策结果可复现sessionKey 可恢复失败时宁可拒绝也不要猜fail-closed4.3 默认账号与回退账号默认账号是事故高发点默认必须是最低权限回退账号不等于“更高权限账号”建议定义defaultAccountId: 只允许“只读/低风险”工具fallbackAccountId: 仅用于同权限域的可用性提升例如同 tenant 的备用 bot禁止跨 tenant、禁止提升 scope5. 最小权限Least Privilege在多账号里的落点多账号不是“多几套 token”那么简单它是把权限切成了多个桶。5.1 token scope 分层建议按能力把账号分层L0只读查询、总结L1低风险写发消息、写文档L2高风险写删改、转账、发邮件/发帖L3管理员配置变更、密钥轮换、kill switch5.2 账号与工具能力的绑定工具层面建议做 capability gatingaccountId - allowedTools/toolScopespolicy engine 在执行前检查 account 的 scope5.3 不允许“隐式升级”典型坏味道“这个账号没权限那我换个有权限的账号帮你做”正确做法fail-closed 提示需要授权/切换或走 delegation 流程见第 12 节6. memory / cache / vector index最容易串线的三兄弟多账号的安全边界80% 的事故来自存储层。6.1 memory namespace 的强制规则最低要求memory key tenantId/accountId/sessionKey任何读写必须携带这三个字段6.2 cache 的 key 设计常见坑cache key 只用userId导致不同 tenant 命中同一个缓存正确做法cache key 至少包含tenantId accountId userId6.3 vector index 的硬过滤向量检索最危险因为“看起来像在搜相似内容”。必须每条 embedding 都带tenantId/accountIdquery 必须加 filtermetadata filter否则拒绝7. webhook / ingress入口映射必须唯一多账号最核心的工程事实入口决定身份。7.1 ingressKey推荐把每个账号的入口定义成一个不可猜测的 key/webhook/ingressKey/slack/webhook/ingressKey/feishu7.2 二次验签推荐入口 key 只是路由仍需要 provider 的签名验签。Slack: signing secretFeishu: event verification token7.3 唯一性合约必须保证ingressKey 全局唯一ingressKey - accountId 映射不可变至少不能 silent change8. sessionKey把 accountId/tenant 编进“可恢复主键”建议 sessionKey 规则env:env|ch:channel|t:tenantId|a:accountId|c:conversationId关键好处任何一次恢复都能校验 accountId 是否一致事故排查能直接 grep sessionKey9. 审计Audit追责必须能回答 3 个问题每一次工具调用/消息发送必须能回答用的哪个 accountId代表哪个 tenant/workspace是谁/什么触发的user / cron / webhook / tool建议 auditEvent 字段timestamp, env, tenantId, accountId, sessionKey, ingressKeyactorType (user|system|cron|webhook|agent)action (tool:message.send)resource (chatId/docId/...)decision (allow|deny|degrade|require_confirm)10. 常见事故与防呆10.1 账号串线A 收到消息B 回复根因session 没绑定 accountId 或恢复时没校验。对策session 创建时写死 accountId每次处理入站时校验resolvedAccountId session.accountId不一致直接 quarantine10.2 误把 admin 号当默认对策默认账号必须低权限admin 号只能显式调用10.3 webhook 回调混淆对策ingressKey path 分流provider 侧签名验签 tenant/workspace id 双重校验11. 账号切换 UX你要的不是“切换”是“解释”产品层面切换必须可解释我现在用的是哪个账号为什么用这个我能不能换换了会带来什么权限变化建议提供/whoami返回 accountId/tenant/env scopes/accounts列出可用账号与权限等级/use accountId显式切换12. delegation唯一允许的“跨账号/跨权限”路径如果你允许跨账号做事必须是“显式委派”而不是 agent 自己猜。最小 delegation 流程低权限账号收到请求policy 判断需要更高权限生成 delegation request可审计用户/管理员批准后才允许用高权限 account 执行delegation event 必须写入 audit并绑定fromAccountId - toAccountIdrequestIdapprovedBy13. 反例不要做这些不要把多账号做成“一个 session 里随时换 token”不要让 agent 自己决定用哪个账号除非规则极其明确并可审计不要共享 memory/vector index哪怕你觉得数据不敏感不要让 fallback 去更高权限域14. 生产落地多账号“强隔离”实现蓝图可直接抄这一节是把前面 1~13 的原则落到工程结构上你复制完以后系统在默认情况下就“很难串线”。14.1 Account Registry单一真相表SSOT目标所有账号、入口、tenant/env、secretRef 都在一个 registry 里声明任何路由/恢复/审计都以它为准。registry 里至少包含envtenantIdaccountIdingress.keys[]全局唯一secrets.*Refcapabilities允许的工具/权限等级14.2 Ingress → accountId不可逆映射用ingressKey路由到 account同时做 provider 签名验签防伪造tenant/workspace id 作为二次校验防错配原则映射失败拒绝处理宁可丢消息也不要串线。14.3 sessionKey 编码 恢复一致性校验fail-closedsessionKey 必须编码env/tenantId/accountId恢复 session 时必须校验这些字段与 ingress resolve 结果一致不一致直接 quarantine并触发告警14.4 namespacememory/cache/vector index 一路带到底memory root:memory/env/tenantId/accountId/...cache key:env:tenant:account:user:...vector metadata filter:{env, tenantId, accountId}必填14.5 tool wrapper强制注入 accountId policy gate audit把工具调用包一层强制写入 trace ctxenv/tenantId/accountId/sessionKey/ingressKeypolicy 先判定allow/deny/degrade/require_confirm写 auditEvent字段缺失bug14.6 两类熔断最小版account mismatchresolvedAccountId ! session.accountId → quarantine ingress kill sessionprivilege escalation请求触发高权限工具但无 delegation → deny 告警14.7 上线前 30 分钟最小落地清单ingressKey 全局唯一合约测试sessionKey 编码 env/tenant/accountstorage namespace 硬隔离vector filter 必填auditEvent 字段齐全缺字段bugkill switches 可用account/ingress/degrade15. 小结多账号不是“多放几套 token”而是把系统拆成多个“安全域”。你要的结果是任何请求都能被唯一映射到 accountId/tenant任意一次恢复都不会换身份任意一次工具调用都可追责出事故时能一键止血kill/quarantine/degrade16. 把 Multi-Account 做成可观测、可验证、可回滚的系统这节是把“强隔离”再向前推进一步把它变成“可持续运营”的能力。16.1 Account Trace Context统一字段集强烈建议把以下字段作为“全链路必填”envtenantIdaccountIdsessionKeyingressKey16.2 Account Mismatch Sentinel绑定一致性哨兵比对 resolvedAccountId 与 session.accountId不一致fail-closed 写 audit 告警16.3 Privilege Escalation Sentinel防隐式升级禁止隐式跨 accountId 调用只有 delegation 才能跨16.4 Multi-Account Contract Tests合约测试最小要测ingress key 唯一accountId/env/tenant 组合唯一session 恢复绑定一致namespace 不可跨读写audit 字段齐全16.5 三类 Kill SwitchAccount kill停用某个 accountId 的所有执行Ingress quarantine隔离某个 ingressKeyDegrade整体降级只读/只总结16.6 5 分钟事故止血路径发现串线风险 → 立即 quarantine ingresskill 对应 account sessiondegrade 到只读取证用 trace ctx 还原链路修复后跑 contract tests policy regression harness16.7 最小落地包你应该复制粘贴的 4 个文件config/registry.jsonSSOTsrc/resolveAccount.tsingress→accountIdsrc/traceContext.ts统一 trace ctx 注入tests/multiAccount.contract.test.ts合约测试16.8 你可以直接抄的最小模板4 个文件16.8.1config/registry.json{version:1,accounts:[{env:prod,tenantId:acme,accountId:slack-acme-bot,ingress:{keys:[k_prod_acme_slack_01]},secrets:{slackBotTokenRef:secret://slack/acme/botToken,slackSigningSecretRef:secret://slack/acme/signingSecret},capabilities:{tier:L1,allowedTools:[message.send,doc.write],denyTools:[drive.delete,admin.rotateSecret]}}]}16.8.2src/resolveAccount.tsimportregistryfrom../config/registry.json;exportfunctionresolveAccountIdFromIngressKey(ingressKey:string){for(constaofregistry.accounts){if(a.ingress.keys.includes(ingressKey))returna.accountId;}thrownewError(UNKNOWN_INGRESS_KEY);}16.8.3src/traceContext.tsexporttypeTraceCtx{env:string;gatewayId?:string;tenantId:string;accountId:string;sessionKey:string;ingressKey:string;providerRequestId?:string;};exportfunctionwithTraceTextendsobject(ctx:TraceCtx,extra?:T){return{...extra,trace:ctx};}16.8.4tests/multiAccount.contract.test.ts7 条规则的最小版用你习惯的测试框架即可这里用伪代码表达断言要点importregistryfrom../config/registry.json;test(ingress keys are unique,(){constallregistry.accounts.flatMap(aa.ingress.keys.map(k[k,a.accountId]asconst));constseennewMapstring,string();for(const[k,id]ofall){if(seen.has(k))thrownewError(DUP_INGRESS${k}-${seen.get(k)}${id});seen.set(k,id);}});test(no cross-tenant accounts share ingress,(){// 如果你允许复用明确写 allowlist默认不允许});这 4 个文件的价值不在“代码多优雅”而在于入口映射唯一 session 绑定稳定 存储命名空间硬隔离 审计字段可追责。先把事故面收敛再谈体验优化。