命令行
安装 Python SDK 后就有 preworld-guard 命令,python -m preworld_guard 效果相同。TypeScript SDK 只有 connection-check,见 TypeScript SDK。
preworld-guard [全局选项] <命令> [命令选项]输出是打印到标准输出的 JSON。出错信息从不包含密钥的值。
全局选项
全局选项要写在命令前面。
| 选项 | 环境变量 | 默认值 |
|---|---|---|
--endpoint | PREWORLD_GUARD_ENDPOINT | http://127.0.0.1:8765 |
--token | PREWORLD_GUARD_TOKEN | |
--token-file | PREWORLD_GUARD_TOKEN_FILE | |
--project-id | PREWORLD_GUARD_PROJECT_ID | |
--agent-id | PREWORLD_GUARD_AGENT_ID | python-agent |
--cache | PREWORLD_GUARD_CACHE | .preworld-guard/policy.json |
--token-file 指向存放令牌的文件,没给 --token 时使用。文件是符号链接或其他人可读时拒绝使用。connection-check 和 trial-check 不读它:给这两个命令的令牌要用 --token 或 PREWORLD_GUARD_TOKEN。
命令
| 命令 | 做什么 | 需要令牌 |
|---|---|---|
connection-check | 检查一个接入包 | 需要(执行器) |
register | 注册一次执行器 | 需要(执行器) |
policy | 拉取并缓存当前策略 | 需要(执行器) |
heartbeat | 发一次心跳 | 需要(执行器) |
policy-validate | 编译一份策略文件 | 不需要 |
policy-schema | 输出策略的 JSON Schema | 不需要 |
policy-replay | 在本地按策略回放动作 | 不需要 |
mcp-proxy | 运行 MCP 代理 | 需要(执行器) |
mcp-origin、mcp-manifest | 查看和批准 MCP 上游及工具的摘要 | 需要 |
mcp-auth | 连接、查看或解除某个用户对 MCP 上游的 OAuth 授权 | 用户自己的访问令牌 |
sandbox | 在 srt 里运行命令,或检查主机 | 不需要 |
siem-export | 把事件和审计导出为 NDJSON | 需要(viewer) |
diagnose | 生成诊断包 | 需要(执行器) |
trial-init | 为某个框架生成接入的起步文件 | 不需要 |
trial-check | 检查自部署环境是否就绪 | 需要 |
onboard | 在自部署控制面上开通组织和项目 | 初始化密钥 |
connection-check
preworld-guard connection-check --config guard-connection.json [--output report.json]检查凭据、执行器是否在线、当前策略是否已加载、是否收到首条事件。不执行任何业务工具。四项都就绪时退出码为 0,否则非 0。
register
preworld-guard --project-id "$PREWORLD_GUARD_PROJECT_ID" --token "$PREWORLD_GUARD_TOKEN" register --name support-agent--name(默认 python-sdk)、--version(默认是 SDK 的版本)。长驻的 Agent 改用 guard.start()。
policy
拉取当前策略,校验后写入缓存,并打印策略。
heartbeat
为这个执行器发一次心跳。
policy-validate
preworld-guard policy-validate policy.yaml编译 YAML 或 JSON 格式的策略,打印编译结果和 policy_hash。有任何格式错误都会失败。
policy-schema
preworld-guard policy-schema [--output guard-policy.schema.json]policy-replay
preworld-guard policy-replay --policy candidate-policy.json --records actions.json --output replay-report.json按一份策略回放 1 到 1,000 条完整的动作(文件不超过 2 MiB)。不执行工具,不发送任何东西,报告里只有判定结果。见发布策略。
mcp-proxy
preworld-guard [全局选项] mcp-proxy --upstream <命令...>
preworld-guard [全局选项] mcp-proxy --upstream-transport streamable-http --upstream-url <url> [--header KEY=VALUE]
preworld-guard [全局选项] mcp-proxy --config registry.json [--downstream-transport streamable-http ...]| 选项 | 默认值 | 含义 |
|---|---|---|
--upstream ... | stdio 服务的启动命令,必须放在最后 | |
--upstream-transport | stdio | stdio、streamable-http 或 sse |
--upstream-url | HTTP 和 SSE 用 | |
--header KEY=VALUE | 发给上游的请求头(可重复) | |
--timeout、--sse-read-timeout | 10、300 秒 | 上游超时 |
--config | 多上游注册表,不能和单上游的选项一起用 | |
--downstream-transport | stdio | stdio 或 streamable-http(只限注册表) |
--listen-host、--listen-port | 127.0.0.1、8766 | HTTP 下游用 |
--downstream-token | PREWORLD_GUARD_DOWNSTREAM_TOKEN | 客户端访问 HTTP 下游时必须带的 bearer 令牌 |
--allowed-host、--allowed-origin | PREWORLD_GUARD_ALLOWED_HOSTS、PREWORLD_GUARD_ALLOWED_ORIGINS | HTTP 下游接受的 Host 和 Origin(可重复) |
--subject-id | PREWORLD_GUARD_SUBJECT_ID | 可信的服务主体,审批需要 |
--sandbox 和 --sandbox-* | 在 srt 里运行 stdio 上游,见沙箱 |
见 MCP 代理。
mcp-origin
preworld-guard mcp-origin --config ./mcp.json --server NAME [--approve SHA256]显示上游的身份摘要。加 --approve 时批准它。
mcp-manifest
preworld-guard mcp-manifest --config ./mcp.json --server NAME --kind tool --name TOOL [--approve SHA256]--kind 取 tool、resource 或 resource_template。显示当前元数据的摘要。加 --approve 时批准它。
mcp-auth
preworld-guard mcp-auth connect --upstream finance \
--endpoint https://guard-proxy.example.com --token-file /private/employee-access-token子命令是 connect、status 或 disconnect。--endpoint 是你们 MCP 代理的 HTTP 下游地址,不是控制面。令牌文件里放的是用户自己从身份提供方拿到的访问令牌,不是执行器凭据。--no-browser 不打开浏览器,改为打印一个一次性链接。connect 授权成功时退出码为 0。见 MCP 代理。
sandbox
preworld-guard sandbox verify --executable tooling/node_modules/.bin/srt
preworld-guard sandbox run --workspace ./workspace --deny-read ~/.ssh -- python agent.pyverify 只有所有探针都通过才以 0 退出。run 原样返回命令的退出码。选项见沙箱。
siem-export
PREWORLD_GUARD_TOKEN="$GUARD_VIEWER_TOKEN" preworld-guard \
--endpoint https://guard.example.com --project-id "$PREWORLD_GUARD_PROJECT_ID" \
siem-export --output /var/lib/preworld-guard-siem/events.ndjson \
--state /var/lib/preworld-guard-siem/cursor.json--limit(默认 500)、--max-pages(默认 20)。见事件、审计与导出。
diagnose
preworld-guard [全局选项] diagnose --framework langchain --output guard-diagnostics.json [--send-ping]检查解释器、框架依赖、策略来源、生命周期和事件队列,写出一个只有你自己可读的诊断包。包里只有白名单内的字段,从不读取参数值或环境变量的值。--send-ping 还会发一条诊断事件。一切正常时退出码为 0,否则为 2。
trial-init
preworld-guard trial-init --framework openai-agents --directory ./guard-trial为 python、langchain、langgraph、claude、openai-agents、pydantic-ai、google-adk、agent-framework、llama-index、agno、dspy 或 crewai 生成起步文件。不会覆盖已有文件,模板里的令牌都是占位符。
trial-check
preworld-guard [全局选项] trial-check [--mcp-config ./mcp.json] [--sandbox-executable srt] [--output report.json]检查到控制面的 HTTPS、凭据、策略版本和 MCP 上游摘要。加 --sandbox-executable 时还运行沙箱探针。提供 viewer 令牌(--viewer-token)和预期出口清单(--expected-exits)时,还报告执行器、资产和策略的覆盖情况。就绪时退出码为 0。它代替不了在目标网络里做一次本应失败的测试。
onboard
preworld-guard --endpoint https://guard.example.com \
onboard \
--bootstrap-token "$PREWORLD_GUARD_BOOTSTRAP_TOKEN" \
--organization 'Example' \
--project 'support-agent'只用于自部署。每调用一次就新建一个组织和项目,owner 令牌只返回这一次。见自部署控制面。