权限与沙箱:能调用,不等于能执行
模型已经提出一个命令,系统还必须回答:是否允许、是否需要审批、在哪些文件和网络边界内运行,以及失败后能不能重试。安全不是在提示词里写一句“请小心”。
精读使用 ToolOrchestrator 的执行类工具路径。不是所有工具都经过同一套进程沙箱,也不能把本课概括成 Codex 全部安全机制。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。
本站必背 · 走路复习
第 8 站:能调用,不等于获准执行
先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。
核心背诵段 · 点击展开或遮住
第八站关注 Core 工具执行中的权限和安全边界。模型提出调用,不等于获得执行授权。用户委托决定任务范围,审批策略决定何时需要额外批准,沙箱和权限环境约束实际能访问什么,领域校验与事务保护业务规则。使用 ToolOrchestrator 的工具,由它协调审批、沙箱选择、执行尝试和受限重试;被禁止就停止,需要审批就先等结果,不能先做后问。Never 表示不发起相应审批,不代表无限权限;执行失败也不能随意放宽限制。记住:授权不等于业务正确,取消不等于撤销;已经发生的副作用,需要正式撤销或补偿机制,并向用户报告事实。
复述顺序:用户范围 → 审批条件 → 资源限制 → 业务校验 → 失败与恢复边界。
背诵用于抓牢主线。理解自测:用户点击停止后,为什么已经写入工程的数据不一定自动恢复? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。
先听一遍,再对照源码
普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。重点区分“是否要问”与“实际允许做什么”。
点击开始;页面不会自动播放,也不会自动标记课程通关。
点击任一章,从对应位置开始。
展开音频文字稿 · 听不清时对照看
声音中的术语,对应代码里的哪个词?
AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。
先定位:这一站到底在讲哪一层?
ToolOrchestrator 位于 Core 的工具执行基础设施中。使用它的执行类工具,将具体请求和运行上下文交给它,由它协调审批、沙箱选择、尝试与受限重试。
这是一个运行时边界,不是 TUI 的弹窗函数。客户端可以展示审批请求,但是否批准、允许什么范围、实际执行器怎样限制行为,需要沿完整调用链分别验证。
- 1收到工具请求与环境上下文
- 2计算本次审批要求
- 3禁止/需审批/无需本次审批
- 4选择适用执行隔离与权限
- 5执行一次并观察真实结果
- 6只有满足条件才进入重试支路
| 粒度 | 负责什么 | 不要误认为 |
|---|---|---|
| 用户授权与业务范围 | 决定被委托做什么 | 不是模型自己的执行建议 |
| 审批策略 | 决定何时要求批准以及如何处理批准结果 | 不是文件与网络访问权限本身 |
| 沙箱/权限环境 | 约束实际执行能够触达的资源 | 不是业务正确性的证明 |
| 领域命令与事务 | 校验工程规则并管理一致性、撤销和审计 | 不是聊天框里的确认文案 |
两个独立问题:要不要问?能做到哪?
审批解决“这次是否需要额外批准”。沙箱和权限配置解决“真正运行时,哪些文件、网络和进程能力可以使用”。两者有关联,但不是同一个开关。
例如:不需要弹窗,可以是动作已在允许范围内;也可能是系统不允许再询问,只能在现有约束内执行或失败。绝不能把“从不询问”解释成“所有事情都放行”。
GEODYNA 还多一层领域安全:操作系统允许写文件,也不代表允许把某个算例里的边界条件修改成不合法状态。审批、执行隔离、领域校验必须各守自己的职责。
| 词 | 具体是什么 | 不要混淆 |
|---|---|---|
| approval_policy | 决定审批行为的配置 | 不是 API 登录密钥 |
| sandbox / permission profile | 实际执行的环境与资源限制 | 不是问一次“可以吗” |
| ToolError::Rejected | 动作被拒绝的错误结果 | 不是要求偷偷换一种命令执行 |
| CancellationToken | 通知正在执行的工作停止 | 不是自动撤销已经提交的副作用 |
源码一:三种审批要求是枚举分支
1. ExecApprovalRequirement 的三种情况
真实源码 · codex-rs/core/src/tools/sandboxing.rs:152–170
代码较长时可左右滑动;下方按语句和术语拆解。
pub(crate) enum ExecApprovalRequirement {
/// No approval required for this tool call.
Skip {
/// The first attempt should skip sandboxing (e.g., when explicitly
/// greenlit by policy).
bypass_sandbox: bool,
/// Proposed execpolicy amendment to skip future approvals for similar commands
/// Only applies if the command fails to run in sandbox and codex prompts the user to run outside the sandbox.
proposed_execpolicy_amendment: Option<ExecPolicyAmendment>,
},
/// Approval required for this tool call.
NeedsApproval {
reason: Option<String>,
/// Proposed execpolicy amendment to skip future approvals for similar commands
/// See core/src/exec_policy.rs for more details on how proposed_execpolicy_amendment is determined.
proposed_execpolicy_amendment: Option<ExecPolicyAmendment>,
},
/// Execution forbidden for this tool call.
Forbidden { reason: String },| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| enum ExecApprovalRequirement | 用互斥变体表达本次执行的审批要求,而不是一串含糊文字。 |
| Skip { bypass_sandbox, ... } | 本次无需普通审批。是否绕过首次沙箱由专门字段及后续条件决定,不能从 Skip 这个词直接推导。 |
| NeedsApproval { reason, ... } | 需要进入审批路径;reason 是可能存在的理由,Option 表示未必有具体文本。 |
| Forbidden { reason } | 明确禁止本次执行,带拒绝理由。它不是“多问几次就能执行”。 |
| proposed_execpolicy_amendment | 可能提出未来同类命令的策略调整建议,不代表建议已获准或当前权限已自动扩大。 |
2. Never 的真实含义与默认返回
真实源码 · codex-rs/core/src/tools/sandboxing.rs:194–229
代码较长时可左右滑动;下方按语句和术语拆解。
pub(crate) fn default_exec_approval_requirement(
policy: AskForApproval,
file_system_sandbox_policy: &FileSystemSandboxPolicy,
) -> ExecApprovalRequirement {
let needs_approval = match policy {
AskForApproval::Never => false,
AskForApproval::OnRequest | AskForApproval::Granular(_) => {
matches!(
file_system_sandbox_policy.kind,
FileSystemSandboxKind::Restricted
)
}
AskForApproval::UnlessTrusted => true,
};
if needs_approval
&& matches!(
policy,
AskForApproval::Granular(granular_config)
if !granular_config.allows_sandbox_approval()
)
{
ExecApprovalRequirement::Forbidden {
reason: "approval policy disallowed sandbox approval prompt".to_string(),
}
} else if needs_approval {
ExecApprovalRequirement::NeedsApproval {
reason: None,
proposed_execpolicy_amendment: None,
}
} else {
ExecApprovalRequirement::Skip {
bypass_sandbox: false,
proposed_execpolicy_amendment: None,
}
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| default_exec_approval_requirement(...) | 默认审批计算函数;具体工具可以提供自己的要求,不能拿此函数当全部安全策略。 |
| AskForApproval::Never => false | 将 needs_approval 设为假,意思是“不发起这种审批”,不是“权限无限”。 |
| OnRequest / Granular 与 Restricted | 默认路径还要看文件系统是否受限;并非仅看一个 UI 模式名称。 |
| UnlessTrusted => true | 该默认分支要求审批;其他具体策略检查仍需结合完整调用链理解。 |
| Forbidden / NeedsApproval / Skip | 下半段把布尔判断与细粒度策略合成为明确的枚举结果。 |
| Skip { bypass_sandbox: false, ... } | 源码明确:默认跳过审批时,没有顺手把绕过沙箱设为真。 |
源码二:拒绝会返回,审批会等待
3. ToolOrchestrator 消费要求
真实源码 · codex-rs/core/src/tools/orchestrator.rs:209–233
代码较长时可左右滑动;下方按语句和术语拆解。
ExecApprovalRequirement::Forbidden { reason } => {
return Err(ToolError::Rejected(reason.clone()));
}
ExecApprovalRequirement::NeedsApproval { reason, .. } => {
let action = tool
.approval_action(req, &tool_ctx.call_id)
.map_err(|err| {
ToolError::Rejected(format!("could not prepare approval action: {err}"))
})?;
let approval_ctx = ApprovalContext {
review_context: GuardianReviewContext::from(&tool_ctx.step_context),
cancellation_token: Some(tool_ctx.cancellation_token.clone()),
call_id: tool_ctx.call_id.clone(),
tool_name: tool_ctx.tool_name.clone(),
strict_auto_review,
approval_reason: reason.clone(),
retry_reason: None,
network_approval_context: None,
};
tool_ctx
.session
.request_approval(action, approval_ctx)
.await?;
already_approved = true;
}| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| Forbidden { reason } => return Err(...) | 立即返回拒绝错误,后面的正常执行尝试不由这条路径继续。 |
| NeedsApproval { reason, .. } | 需要审批时,先构造对应 action 与上下文。 |
| approval_action(...).map_err(...)? | 若连审批动作都无法正确准备,也转为拒绝;问号把错误向上返回。 |
| ApprovalContext { ... } | 带入步骤审查上下文、取消信号、调用 ID、工具身份和理由,不能只问一句脱离目标的“是否同意”。 |
| request_approval(...).await? | 等待审批路径完成;拒绝或错误会沿 Result 传播,不是先执行后补问。 |
| already_approved = true | 记录这次已经通过相应审批,供后续受控流程使用;不是永久授权所有操作。 |
边界提醒:Skip 分支在 strict_auto_review 条件下仍可能进入审查;它只表示本次普通审批要求,不能概括所有审查机制。
4. 第一次执行的结果先被分类
真实源码 · codex-rs/core/src/tools/orchestrator.rs:309–338
代码较长时可左右滑动;下方按语句和术语拆解。
let initial_attempt_start = Instant::now();
let (first_result, first_deferred_network_approval) =
Self::run_attempt(tool, req, tool_ctx, &initial_attempt, network_approval_spec).await;
let initial_duration = initial_attempt_start.elapsed();
match first_result {
Ok(out) => {
// We have a successful initial result
Ok(OrchestratorRunResult {
output: out,
deferred_network_approval: first_deferred_network_approval,
})
}
Err(ToolError::Codex(err)) => {
let CodexErrorDetails::Sandbox(SandboxErr::Denied {
output,
network_policy_decision,
}) = err.details()
else {
let err = ToolError::Codex(err);
if let Some(outcome) = sandbox_outcome_from_tool_error(&err) {
otel.sandbox_outcome(
&otel_tn,
otel_ci,
outcome,
initial_duration,
/*escalated_duration*/ None,
);
}
return Err(err);
};| 逐句/逐词 | 这段代码实际做了什么 |
|---|---|
| Self::run_attempt(...).await | 在已经选择的尝试配置下运行工具,获得实际结果和可能延后的网络审批信息。 |
| match first_result / Ok(out) | 成功就封装输出返回;这是此执行层的结果,不是整个用户目标验收。 |
| Err(ToolError::Codex(err)) | 进入一个错误类别,再判断是否属于沙箱拒绝。 |
| let ...SandboxErr::Denied... = err.details() else | 只有匹配沙箱拒绝的特定错误才继续考虑该支路;其他错误返回。 |
| 后续重试逻辑 | 还会检查工具是否允许相应失败升级、审批策略、网络约束等,不能简化为“所有失败自动放开沙箱重跑”。 |
取消 ≠ 撤销;重试 ≠ 安全地重复写入
取消是阻止工作继续推进的控制信号。一个命令已经提交造成的写入,不会因为稍后收到取消令牌就自动回滚。能否回滚由具体业务事务、补偿和 Undo/Redo 决定。
同样,重试有两种不同问题:请求是否可以再发一次,以及前一次是否已经产生副作用。对读操作重试和对扣费、提交、工程写入重试,风险不同。GEODYNA 的候选工具应通过命令身份、版本与正式事务边界防止重复提交;这是设计要求,不是声称 Codex 统一替你实现所有工具的业务幂等。
| 产品状态 | 应展示或记录的内容 |
|---|---|
| 等待批准 | 具体目标、改动范围、风险和影响,不把关键差异藏在一句确认里。 |
| 执行被拒 | 说明原因与当前允许范围,不把拒绝当普通故障偷偷规避。 |
| 用户取消 | 报告哪些工作停止,哪些动作已经发生,需要怎样恢复。 |
| 结果不确定 | 先查询状态或用幂等机制确认,不能盲目重复提交写操作。 |
把同一个场景换一种条件
下面是执行安全的教学情境,不会真正申请权限或执行命令。
仅为本地教学演示,不调用模型或 GEODYNA,不执行任何真实操作。
先预测会走哪条分支,再点击按钮查看。
Skip 不自动关闭沙箱
- 默认要求是 Skip。
- bypass_sandbox 仍为 false。
- 具体执行继续服从环境、沙箱和工具自身的约束。
“不用弹窗”与“无限权限”不是同义词。
不进入正常执行
- 构造带目标和上下文的审批动作。
- 审批路径给出拒绝或错误。
- 通过 Result 返回,不先执行后征求意见。
拒绝是必须尊重的控制结果。
在协调器处返回拒绝
- 匹配到 Forbidden。
- 返回 ToolError::Rejected。
- 把明确的拒绝事实向上交还,提供安全可行的下一步。
不要把“用户让完成目标”当作扩大权限范围的依据。
停止与恢复必须分开
- 某个工程命令已在业务边界提交。
- 随后到达取消信号,停止后续推进。
- 核对已发生的事实;必要的恢复由正式撤销或补偿路径执行。
取消令牌不是时间倒流,也不能保证已经写入的数据不存在。
最容易说错的边界
| 常见说法 | 准确表述 |
|---|---|
| Never 等于全部允许 | 它描述不发起某类审批;实际资源访问仍受环境与工具约束。 |
| 审批通过就不可能破坏工程 | 授权不替代领域校验、事务与正确性验证。 |
| 任何失败都该放宽权限重试 | 只允许在授权范围、特定错误和策略条件内进入相应重试。 |
| 点击停止,所有已执行操作自动撤销 | 取消与撤销是不同机制;需要报告已经发生的事实。 |
迁移到你的 GEODYNA 智能体
以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。
候选危险操作确认应明确:目标工程和对象、即将变更的字段、是否覆盖已有内容、预期影响以及恢复方式。确认时还要防止预览后对象状态变化,使用户批准的是旧内容却执行了新内容。
真正的写入经正式 Command API、事务、Undo/Redo 和审计路径完成。提示词可以引导模型,但不能替代这些可信执行边界。
| 你要设计的点 | 可验证的证据 |
|---|---|
| 确认与实际动作一致 | 保存目标身份和预览版本,提交前重新校验。 |
| 拒绝后无副作用 | 检查工程状态、历史记录和输出文件,不能只检查弹窗是否关闭。 |
| 取消后的事实可说明 | 列出已提交与未执行部分,需要恢复时走正式撤销。 |
| 重复提交可控制 | 用业务命令身份与版本检查验证重复请求不会叠加危险写入。 |
产品经理练习:为“覆盖当前算例的某组设置”写一张确认卡和 4 条验收用例,其中必须有拒绝、状态过期和取消。
先答小测,再看解析
每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。
1. Skip 一定表示绕过沙箱吗?
2. Forbidden 分支在协调器中做什么?
3. AskForApproval::Never 在默认计算里表示什么?
4. 用户取消时,已提交工程写入是否自动撤销?
5. 预览后目标版本发生变化,提交时应怎样?
最后一句话交作业
请分别解释审批策略、沙箱、领域校验;再说明 Never 为什么不等于无限权限,取消为什么不等于撤销。
展开参考答案(先自己说一遍)
审批策略决定何时要求额外批准;沙箱与权限环境约束实际资源访问;领域校验与事务保护工程规则和一致性。Never 表示不发起相应审批,不会自动扩大权限。取消停止后续推进,已提交副作用要由正式撤销或补偿路径处理。
下一轮再回来时:第三轮追审批等待与取消状态;第四轮再看工具特定策略、不同平台执行器和失败重试的完整条件。