AgentRQ 是一款自托管的 Human-in-loop（人在回路）AI Agent 实时任务管理工具，它的核心安全模型由三大支柱构成：标准OAuth2授权流程、AES-GCM 加密存储的 Workspace 令牌，以及覆盖工具调用的多层权限防护机制。无论你是想在团队内部署一套安全的 Agent 调度平台，还是单纯好奇"让 AI 替我干活时，如何保证它不越权"，这篇指南都能帮你快速看懂 AgentRQ 是如何把密钥、令牌和审批流层层锁死的。

一、安全边界全景图：谁访问谁，用什么凭证

AgentRQ 把系统划分为几类清晰的边界，每一类都有独立的认证机制。完整定义可以在架构文档 ARCHITECTURE.md 的 "Security Boundaries" 一节找到，核心内容如下：

这个设计的精髓在于**"一个凭证只干一件事"**：人的令牌、Agent 的令牌、终端票据、OAuth 同意票据全部互相隔离，任何一张偷来的票据都换不来第二种权限。

二、OAuth2 授权：人类必须亲手按下 "Allow"

AgentRQ 同时对外暴露两类 MCP 服务：面向 Supervisor Agent 的 Core MCP（/mcp）和面向 Worker Agent 的单 Workspace MCP（/mcp/{workspaceId}）。两者的认证细节都写在 auth.md 中。

对新手来说，最关键的一条设计原则是：任何凭证都以某个人的名义签发，且必须由本人在浏览器中批准。Agent 自己无法注册账号、无法自行换取令牌，因此授权服务器元数据里根本没有agent_auth通道。

授权码流程：人类始终在回路里

1. Agent 把用户的浏览器带到/oauth2/authorize，附带response_type=code、client_id、redirect_uri与state；
2. 用户未登录则先登录 AgentRQ；
3. 用户看到同意页面——上面写清楚"哪个应用在申请、它能做什么、回调地址在哪里"，然后亲手按Allow或Deny；
4. 允许后应用拿到code，用它去/oauth2/token换取访问令牌。

同意页面由后端独立渲染（见 consent.go），而不是由前端 Vue 应用渲染。源码注释写得很直白：这样"任何 Agent 能驱动的东西——WebMCP 工具或 REST API——都无法替某人按下 Allow"。

防 CSRF、防重放：同意令牌绑定"人 + 请求"

同意页面提交时携带的 OAuth Consent Token 会同时校验三件事（见 jwt.go）：

• Subject：必须是渲染此页面的那个人；
• Audience：必须是oauth_consent，其他类型的令牌一概不认；
• 完整载荷：应用 ID、资源、redirect_uri、state必须与授权请求逐字段一致。

这意味着你为 A 应用批准的授权，绝不能被挪到 B 应用或另一个回调地址上使用。整个同意令牌只有10 分钟有效期，超时就得重新走一遍流程。

客户端注册也自带"反 SSRF 装甲"

AgentRQ 支持 RFC 7591 动态客户端注册，还支持较新的CIMD（Client ID Metadata Document）方案——让client_id直接是一个 HTTPS 元数据文档 URL。由于这个 URL 由调用方提供，服务端在 cimd.go 中做了非常激进的加固：

• 自行解析 DNS，任何解析结果落在回环、内网、链路本地地址的请求直接拒绝；
• 额外封锁 NAT64（64:ff9b::/96）、6to4 等能"把 IPv4 藏进 IPv6"的地址段，堵住重绑定攻击；
• 绝不跟随 HTTP 重定向，响应体限制 5KB，只接受 200 状态码；
• 明确拒绝client_secret字段——CIMD 客户端永远不能是"共享密钥型"机密客户端。

三、AES-GCM 加密：Workspace 令牌如何"入库即密文"

Worker Agent 连接 Workspace MCP 时用的凭证，是一个 16 字符的 Workspace 令牌。这个令牌在数据库里从不以明文存储——它使用 AES-256-GCM 加密，密钥来自服务端 32 字节的配置项。

加密实现位于 security.go，几个值得新手注意的工程细节：

• GCM 模式自带完整性校验：解密时若密文被篡改或 nonce 被重放，gcm.Open会直接报错，而不是解出一串乱码让你误以为是合法数据；
• 每次加密随机生成新 nonce（crypto/rand产生），避免同一明文+同一密文的模式泄露；
• 密钥长度强制校验：不是 32 字节直接拒绝，错误信息明确提示 "key must be 32 bytes for AES-256"；
• 同文件还提供两个"防君子"工具函数：
  • GenerateSecret：用crypto/rand.Int生成无模偏差的随机密钥串（用于各种 secret 的初始生成）；
  • SecureCompare：基于crypto/subtle.ConstantTimeCompare的常数时间比较，防止通过响应耗时差异发动时序攻击。

一句话总结：令牌在磁盘上是密文，在网络上是 Bearer 头，在验证时是常数时间比较——三个环节各管一段。

四、JWT 受众隔离：一张令牌只配一个"工牌"

AgentRQ 的所有令牌都是 HS256 签名的 JWT，但真正的安全感来自audience（受众）隔离。jwt.go 中定义了多组互不通用的受众：

几个设计非常值得借鉴：

• 短命票据走 URL 传输。终端/浏览器票据会出现在 URL 查询串里（可能被代理日志、shell 历史记录看到），所以只给 1 分钟寿命，每次重连重新签发，绝不复用；
• 刷新令牌刻意不带 email/name 字段，每次刷新都从数据库现查现签发，避免"一个月前的旧名字"复活；
• 所有校验函数都强制检查签名算法必须是 HMAC，防算法混淆攻击（即伪造alg=none或换成非对称算法的常见 JWT 攻击）。

五、多层权限防护：Agent 调用工具前，先过三关

光有身份认证还不够，AgentRQ 对Agent 的每一次工具调用都做了门控。

第一关：Workspace 隔离

每个 workspace 有独立的 MCP 服务实例，Worker Agent 认证成功后只能看到自己这个 workspace——它的任务、消息、记忆、技能，看不到隔壁 workspace 的任何东西。跨 workspace 的操作必须走 Supervisor 通道的 OAuth2 用户级令牌。

第二关：Auto-allow 规则

Workspace 可以配置"免审批工具清单"（见 autoallow.go）。规则有三种粒度：

• MCP 工具：mcp_servername_toolname精确匹配；
• Shell 工具：Bash:git *这类基础命令通配（git status放行，rm -rf不放行）；
• 普通工具：按工具名精确匹配，如Read、Write。

第三关：人工审批流

未命中 auto-allow 规则的危险操作，Agent 的调用会挂起等待人类批准：请求经 SSE 推送到你的 Web/移动端界面，你在手机上点一下 Allow 或 Deny，结果再通过 MCP 通知回 Agent。这正是 AgentRQ "Human-in-loop" 名的由来——AI 跑得再快，油门也在人手里。

此外还有按用户的请求限流（workspace/task/message/telemetry/import 各自独立计数，见 ratelimit.go）和可配置的按 IP DDoS 防护（默认 20 请求/秒、超限封禁 5 分钟，见 .env.example 中的AGENTRQ_DDOS_*配置）。

六、守护进程侧：机器凭证也有一层保险

当你用agentrqd守护进程把本机注册到 AgentRQ 时，机器令牌（machine token）的保管同样讲究：

• 注册必须人在机器前：一次性注册码由人亲手敲进目标机器的终端，没有远程注册通道（见 enrol.go）；
• 令牌落盘即最小权限：每个 profile 一个独立文件，权限0600；父目录0700——即使文件被读出，目录权限也挡住了"到底有哪些 profile"这种元信息泄露（见 store.go）；
• 文件路径构造处会二次校验 profile ID 字符集，专门防御目录穿越攻击。

七、总结：AgentRQ 安全模型的三层纵深

对自托管用户来说，这套模型意味着三件实在的事：你持有自己的 Claude 订阅和机器，凭证永远签发在你的服务器名下；Agent 的能力边界由你划定，从精确到单条命令；每一类风险都有对应的最小化凭证，令牌泄露的爆炸半径被压缩到"一个用途、一分钟到两天"。

如果想深入源码，推荐按这条路径阅读：security.go → jwt.go → cimd.go → auth.md → consent.go，基本就能把 AgentRQ 的整个安全模型走通一遍。