Skip to content

常见问题 ​

代码是错误响应里的 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_DENYdefault_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_INVALIDYAML 有错在编辑器里点那条错误,跳到对应的行

预演显示「信息不足」 ​

控制面只知道参数名,不知道参数值,所以按参数值写的规则没法从事件判断。这是正常的。要检查这类规则,下载候选,在你们这边运行 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 421Host 不在 --allowed-host 里加上 Agent 实际使用的主机名
加了 --sandbox 后代理启动失败没装 srt,或者版本不是 0.0.77安装锁定的版本,再运行 preworld-guard sandbox verify

还是解决不了 ​

运行 preworld-guard diagnose --output guard-diagnostics.json,然后通过我们的联系页面联系,我们会告诉你们怎样发送这个文件。文件里没有参数值、环境变量的值或任何密钥。