84 lines
3.0 KiB
Markdown
84 lines
3.0 KiB
Markdown
# 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` 限制
|