PaddedCell/plans/PROXY_PC_EXEC.md

PROXY_PC_EXEC

背景

新增一个可代理执行的安全命令工具，整体行为尽量保持与现有 pcexec 一致，但允许在受控条件下以指定的代理身份注入 AGENT_ID。

开发想法整理

1. 新建工具 proxy-pcexec

• 新增一个工具：proxy-pcexec
• 目标是复用或对齐现有 pcexec 的能力与行为
• 预期执行语义与安全边界尽量和 pcexec 保持一致，避免出现两套不同标准

2. 扩展 openclaw.plugin.json

需要在 openclaw.plugin.json 中新增配置字段：

• config.proxyAllowlist

兼容性说明：

• 如有需要，也可兼容读取 proxy-allowlist 作为别名

用途：

• 用于声明哪些 agent 允许调用 proxy-pcexec
• 只有在该 allowlist 中的 agent，才具备调用该工具的权限

建议约束：

• config.proxyAllowlist 应为 agent 标识列表
• allowlist 仅支持精确匹配，不支持通配、分组或模糊匹配
• 若调用方不在 allowlist 中，应直接拒绝调用
• 默认配置应偏保守；未配置时建议视为不允许任何 agent 调用
• 一旦调用方 agent 在 allowlist 中，则允许其代理任意 proxy-for 值

3. proxy-pcexec 与 pcexec 的关键区别

proxy-pcexec 的功能与 pcexec 基本一致，核心差异如下：

pcexec

• 直接将调用者的 agent-id 注入环境变量 AGENT_ID

proxy-pcexec

• 不直接使用调用者的 agent-id 作为 AGENT_ID
• 增加一个必填工具参数：proxy-for
• 实际注入到环境变量 AGENT_ID 中的值，取自 proxy-for

建议的行为规则

调用参数

proxy-pcexec 至少包含：

• command
• proxy-for（必填）
• 其他参数可尽量与 pcexec 保持一致

权限校验

调用 proxy-pcexec 时应至少进行以下校验：

1. 校验调用方 agent 是否在 config.proxyAllowlist 中（精确匹配）
2. 校验 proxy-for 是否存在且非空
3. 不要求 proxy-for 必须是已注册或已知 agent-id，可自由填写
4. 通过校验后，再执行与 pcexec 等价的命令执行流程

说明：

• allowlist 控制的是“谁可以发起代理执行”
• 只要调用方 agent 在 allowlist 中，就允许其代理任意 agent

环境变量注入

• AGENT_ID = proxy-for
• PROXY_PCEXEC_EXECUTOR = 调用方真实 agent-id
• PCEXEC_PROXIED = true
• 不应再把原始调用者的 agent-id 直接写入 AGENT_ID

设计目标

• 保持与 pcexec 尽可能一致，降低维护成本
• 通过 allowlist 控制谁可以发起代理执行
• 通过显式 proxy-for 参数，避免隐式身份继承
• 让代理身份切换是显式、可审计、可配置的

日志与审计

建议日志至少记录：

• executor（调用方真实 agent-id）
• proxy-for
• 最终执行命令

已明确的设计结论

• proxy-for 可以随意填写，不要求必须是已注册 agent
• 日志需要记录 executor 和 proxy-for
• config.proxyAllowlist 仅支持精确匹配
• allowlist 中的 agent 可以代理任意 agent，不需要额外的 proxy-for 限制