细粒度能力

每条路由只有一个端点 id，每个端点一条规则，决定它能不能被调用，以及路径、命令、大小和频率限制。规则前面没有第二道门。agents-cli 只放开会话相关的几条 Agents 路由，POST /shell 和 POST /v1/agents 保持关闭，用的就是这一层。

设计评审稿在 细粒度能力设计。路径和命令的执行细节在 文件与命令控制。Agents 请求和响应在 Agents API。完整路由表在 Agents API 参考。

一个开关：端点

端点 id（upload、files_list、agents_sessions_create）是所有环节共用的单位：策略、审计日志、GET /capabilities 和客户端。组只是一组端点 id 的名字。写 groups: [file_ops]、group:file_ops、table.enable_group(CapabilityGroup.FILE_OPS) 或 ABX_SERVER_ENABLED_GROUPS=file_ops，都会展开成该组声明的端点 id，得到同一份逐端点规则。

默认值：core 永远开着。agents、dev_tools、browser 是可选组，默认关。file_ops、process、terminal、system、commands 默认开。health、capabilities、capabilities_check 不能关掉。

规则来自五层，按端点合并：

更具体的选择器优先：精确 id 优于 glob，glob 优于 group:<name>。同样具体时，后面的层优先；同一层里只要有一条 enabled: false，该端点就是关的。所以策略里的 endpoints.code_run.enabled: false，即使环境变量打开了 dev_tools，它也仍然是关的。

拒绝会指出是哪条规则拒绝的。404 正文带 code: endpoint_disabled 和 rule，例如 policy:endpoints.shell、policy:groups.process、preset:read-only、code:enable_group:file_ops、default:opt-in:browser。GET /capabilities 逐端点报告同一个 rule。它的 groups 和 group_summary 由端点状态推导（{"file_ops": {"enabled": 11, "total": 12}}），不单独存储。

ABX_SERVER_ENABLED_GROUPS 是唯一的组环境变量，值是逗号分隔的组名，例如 agents,dev_tools。未知名字会让进程带着拼写建议退出。没有用来关闭组的变量，请写 groups: {process: false} 或 endpoints 规则。

如何启动

三种入口，服务端用同一份文档。无效文档会阻止启动，不会退回成全部允许。

template.yaml 的 server: 块。工具链把它编译成 /etc/agent-sandbox/server-policy.json。可用的键：version、preset、base_dir、groups、defaults、auth、endpoints、description。groups 可以是要打开的组列表，也可以是组到 true/false 的映射。

server:
  endpoints:
    "*":
      enabled: false
    agents_sessions_create:
      enabled: true
    agents_sessions_events_create:
      enabled: true
    agents_sessions_items_list:
      enabled: true
    agents_runtimes_list:
      enabled: true

组的简写，列表或映射：

server:
  groups: [agents, dev_tools]     # 等价于 {agents: true, dev_tools: true}

server:
  groups:
    process: false
    terminal: false

内联 JSON：

export ABX_SERVER_POLICY='{"groups":["agents"],"endpoints":{"*":{"enabled":false},"agents_sessions_create":{"enabled":true}}}'

或文件：

export ABX_SERVER_POLICY_FILE=/etc/agent-sandbox/server-policy.json
agent-sandbox-server check-config --policy /etc/agent-sandbox/server-policy.json

查找顺序：ABX_SERVER_POLICY，然后 ABX_SERVER_POLICY_FILE，然后默认路径上的策略文件。都没有时用内置默认：可选组关，其余全开，没有逐端点限制。

Python：

from agent_sandbox.server import SandboxServer, ServerPolicy

policy = ServerPolicy.only(
    "agents_sessions_create",
    "agents_sessions_events_create",
    "agents_sessions_items_list",
    "agents_runtimes_list",
)
SandboxServer(policy=policy).serve(port=9000)

ServerPolicy.only 先把 "*" 关掉，再打开列出的 id，并保留 core 端点。agents-cli 的 commands.py 就是这个调用。only 还接受 "transfer"（上传下载的四个 id）和 "group:<name>"。

不写策略文档、在 commands.py 里打开整组：

from agent_sandbox.server import CapabilityGroup, default_table

default_table().enable_group(CapabilityGroup.DEV_TOOLS)

enable_group 和 disable_group 是仅有的代码级开关。disable_group(CORE) 会抛错。

选择器

同样具体、同一层里的多条匹配规则冲突时，enabled: false 优先。更具体的选择器可以再打开该端点。

一条规则里能写什么

所有端点都能写的 limits：max_request_bytes、rate_per_minute、max_concurrency。

Agents 端点已经在内置目录里，默认 scope 是 agents:use。和 upload 一样，可以把某一个端点 id 单独设为 enabled: true。这些端点没有 paths，也没有专用 params，所以除此之外只能写 enabled、scopes、audit 和上面三个通用 limits。写上 paths 或专用 params 时，策略加载失败。

预设，写在你的端点规则之前：

组名：core、commands、file_ops、process、terminal、system、dev_tools、browser、agents。core 不能关。

同一个身份既能读有路径范围的文件，又能跑 shell、process_start、code_run 或 PTY 时，检查会给出 L1 警告。进程可以绕过路径规则。Agents 会话由服务端自己拉起 CLI，不需要为此打开 process 组。

端点目录

下表是端点声明表（agent_sandbox.server.endpoints.ENDPOINTS）。路由表、策略和 GET /capabilities 都由它派生。pty_connect 是 WebSocket 升级，在 PTY 端口上提供。Agents 行的 scope 是 agents:use。可配项比带路径的文件路由少，因为这些接口不接收路径或专用参数。

和 Agents API 案例的关系

agents-cli 只启用：

本地 e2e 已确认：POST /shell 是 404，POST /v1/agents（定义）是 404，Codex 和 Qwen Code 的会话、事件、条目仍然 200 / 202。要再开放一条路由，把对应端点 id 加进 ServerPolicy.only 和 template.yaml 的 endpoints。