# 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` 限制