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.proxy-allowlist

用途：

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

建议约束：

• config.proxy-allowlist 应为 agent 标识列表
• 若调用方不在 allowlist 中，应直接拒绝调用
• 默认配置应偏保守；未配置时建议视为不允许任何 agent 调用

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.proxy-allowlist 中
2. 校验 proxy-for 是否存在且非空
3. 通过校验后，再执行与 pcexec 等价的命令执行流程

环境变量注入

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

设计目标

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

待进一步明确的问题

• proxy-for 是否只允许填写已注册/已知的 agent-id
• 审计日志中是否需要同时记录：
  • 实际调用者 agent-id
  • proxy-for 值
  • 最终执行命令
• config.proxy-allowlist 的格式是否需要支持通配、分组或仅支持精确匹配
• 是否需要对 proxy-for 再增加单独 allowlist / 映射限制，避免允许调用者代理任意 agent