常见问题
代码是错误响应里的 code 或判定里的 reason_code,见接口错误码。
安装 SDK
| 现象 | 原因 | 修法 |
|---|---|---|
| 私有 SDK 源返回 401 | 这台机器上没有 SDK 下载令牌,或者令牌已过期、已撤销 | 把控制台给出的那一行写进 ~/.netrc(权限 600),或者重新签发令牌。CI 里用 NETRC 指向一个临时文件 |
| pip 报哈希不一致 | 下载到的文件不是命令里固定的那个 | 原样使用控制台给出的命令,不要手动改版本或地址 |
npm 找不到 @preworld/guard,或者去了公共源 | 项目里没有 .npmrc,或者没设 PREWORLD_GUARD_SDK_NPM_AUTH | 用 .npmrc.example 生成 .npmrc 并提交;把这个变量设成 token:<SDK 下载令牌> 的 base64 |
npx preworld-guard 下载了东西 | 不加 --no 的 npx 在 SDK 没装时会从公共源下载 | 一律在装了 @preworld/guard 的目录里运行 npx --no preworld-guard … |
| 某个 extra 和另一个装不到一起 | [crewai,mcp] 以及 [google-adk,gateway] / [google-adk,oauth] 互相冲突 | 把 MCP 代理或 broker 放到单独的环境里运行 |
向导里没有某个框架,或者报 SDK_ADAPTER_UNAVAILABLE | 向导要安装的 SDK 版本还没有这个框架的适配器 | 在框架适配器里查这个框架要求的最低 SDK 版本。向导要安装的 SDK 有这个适配器,才会提供这个框架 |
检查接入没通过
| 检查项 | 常见原因 | 修法 |
|---|---|---|
| 凭据有效 | 没加载 guard.env,或者接入已撤销、已轮换,或者凭据过期(RUNTIME_TOKEN_INVALID) | 把变量加载进 Agent 的环境。轮换之后要用新的接入包,并重启 Agent |
| 执行器在线 | Agent 没在运行、没调 guard.start(),或者 2 分钟没有心跳(「失联」) | 用 guard.start() 启动 Agent。必须经过公司代理时,设 PREWORLD_GUARD_PROXY(以及 PREWORLD_GUARD_CA_BUNDLE);SDK 不读 HTTPS_PROXY |
| 当前策略已加载 | 执行器还没拉到当前版本(「待确认」),或者还在用旧版本 | 等下一次心跳(大约 15 秒)。一直不变的话,到「执行器」页看它最近的错误 |
| 首条事件已收到 | Agent 还没做过受保护的调用 | 通过一个包装过的工具调用一次。事件一直排队的话,见所有动作都被阻断 |
任意一项,报 AGENT_CREDENTIAL_MISMATCH 或 EVENT_AGENT_MISMATCH | 代码里的 Agent ID 和接入的不一致 | 用 guard.env 里的 PREWORLD_GUARD_AGENT_ID |
| 同一台机器跑多个 Agent,事件停了,Agent 被 403 阻断 | SDK 0.8.0 及更早版本里,从同一目录启动的 Agent 共用一个事件队列 | 升级到 0.9.0,或者给每个 Agent 设各自的 PREWORLD_GUARD_CACHE |
所有动作都被阻断
| 现象 | 原因 | 修法 |
|---|---|---|
连不上控制面一段时间后出现 GUARD_UNAVAILABLE(或者 @guard.tool 抛出 GuardError) | 超过 5 分钟没有成功刷新策略 | 恢复网络连接,下一次刷新后判定恢复。max_stale_age 决定这个时长 |
GuardAuthError,或者执行器显示「凭据已失效」 | 凭据已撤销或过期 | 轮换接入,用新的接入包重启。401、403 之后 SDK 从不退回去用缓存 |
POLICY_EXPIRED | 策略的 expires_at 已过 | 发布一份不带过期时间、或者过期时间更晚的策略 |
GUARD_AUDIT_UNAVAILABLE | 本地事件队列满了,通常是因为事件发不出去 | 修好到控制面的连接,并确认队列所在目录还有空间 |
切到强制执行后一切都是 DEFAULT_DENY | default_effect: deny,但没有放行这些动作的规则 | 加上放行规则,或者回到只观察模式,从观察生成候选 |
SUBJECT_REQUIRED | 有规则拿参数和可信主体比较,这次调用却没有可信主体 | 用 guard_run(subject_id=...) 或适配器的 resolve 传入用户 |
发布被拒绝
| 提示或代码 | 原因 | 修法 |
|---|---|---|
POLICY_V2_NEEDS_EXECUTORS | 格式 v2 的策略,而有活跃的执行器不支持格式 v2 | 升级那个 Agent 的 SDK,或者在「执行器」页把不再使用的执行器退役 |
CANDIDATE_BASE_OUTDATED | 这份候选审核期间,有人发布了别的版本 | 基于当前版本重新起草,再提交独立审核 |
POLICY_REVIEW_BY_AUTHOR、POLICY_REVIEW_SAME_SUBJECT | 作者本人或同一个可信主体在审核 | 由另一个有审核员角色的人审核 |
POLICY_REVIEW_NEEDS_REVIEWER | 管理员想批准策略审核 | 只有审核员角色能批准策略审核 |
CANDIDATE_HASH_MISMATCH | 要发布的策略和审核时的不一样 | 原样发布审核过的候选,或者把改过的版本重新提交审核 |
CANDIDATE_EXPIRED、CANDIDATE_NOT_APPROVED_OR_EXPIRED | 候选过了有效期 | 重新保存成一份新的候选 |
CANDIDATE_NO_OBSERVED_ACTIONS | 观察窗口里没有动作达到次数要求 | 调低最少次数、放宽窗口,或者让 Agent 多跑一段时间 |
POLICY_DSL_INVALID | YAML 有错 | 在编辑器里点那条错误,跳到对应的行 |
预演显示「信息不足」
控制面只知道参数名,不知道参数值,所以按参数值写的规则没法从事件判断。这是正常的。要检查这类规则,下载候选,在你们这边运行 preworld-guard policy-replay,见在你们这边回放。
审批
| 现象 | 原因 | 修法 |
|---|---|---|
APPROVAL_SUBJECT_REQUIRED | 调用没有可信主体 | 用 guard_run(subject_id=...) 传入。MCP 代理启动时加 --subject-id |
恢复时报 APPROVAL_NOT_CONSUMABLE | 票据已用过、已过期、被拒绝,或者参数和批准时不一致 | 重新申请审批。不要让模型改动等待审批的调用的参数 |
POLICY_CHANGED | 申请票据时策略刚好变了 | 按新策略重新发起这次调用 |
审核员遇到 TICKET_SELF_APPROVAL | 这个动作的可信主体就是审核员自己 | 由另一位审核员处理 |
| 批准之后,MCP 客户端仍然一直收到「需要审批」 | 客户端重试时传不了 _meta | 换一个能传 _meta 的客户端,或者改用框架适配器 |
快照一直是 uncertain | 开始执行之后进程停了 | 核对业务系统。Guard 从不自动重放它 |
MCP 代理
| 现象 | 原因 | 修法 |
|---|---|---|
| Agent 的工具列表里没有某个工具 | 策略不准入它、它不在 allowed_tools 里,或者它的元数据变了而被冻结 | 检查策略里的 mcp.admit、注册表,并用 mcp-manifest 批准新的元数据 |
| 用 HTTP 下游时代理起不来 | 有上游的身份还没批准 | 运行 mcp-origin 并批准 |
--allowed-host/--allowed-origin 只适用于 streamable-http 下游。 | 在 stdio 代理上用了 Host 或 Origin 选项 | 去掉它们,或者配合 --config 使用 --downstream-transport streamable-http |
| 代理返回 HTTP 421 | Host 不在 --allowed-host 里 | 加上 Agent 实际使用的主机名 |
加了 --sandbox 后代理启动失败 | 没装 srt,或者版本不是 0.0.77 | 安装锁定的版本,再运行 preworld-guard sandbox verify |
还是解决不了
运行 preworld-guard diagnose --output guard-diagnostics.json,然后通过我们的联系页面联系,我们会告诉你们怎样发送这个文件。文件里没有参数值、环境变量的值或任何密钥。