第一轮 · 第 8 站 · CORE · 执行安全分支入门

权限与沙箱:能调用,不等于能执行

模型已经提出一个命令,系统还必须回答:是否允许、是否需要审批、在哪些文件和网络边界内运行,以及失败后能不能重试。安全不是在提示词里写一句“请小心”。

本站必背:走路时复述这一段

分清审批策略与运行隔离
解释 Skip、NeedsApproval、Forbidden
把取消、撤销和受限重试分开设计

精读使用 ToolOrchestrator 的执行类工具路径。不是所有工具都经过同一套进程沙箱,也不能把本课概括成 Codex 全部安全机制。 讲义已备好 ≠ 已掌握;本页不会改动你的通关状态。

本站必背 · 走路复习

第 8 站:能调用,不等于获准执行

先理解,再背这一个完整段落。日常复述约 1–2 分钟;点标题可遮住正文,按下面的顺序提示试着复述。

核心背诵段 · 点击展开或遮住

第八站关注 Core 工具执行中的权限和安全边界。模型提出调用,不等于获得执行授权。用户委托决定任务范围,审批策略决定何时需要额外批准,沙箱和权限环境约束实际能访问什么,领域校验与事务保护业务规则。使用 ToolOrchestrator 的工具,由它协调审批、沙箱选择、执行尝试和受限重试;被禁止就停止,需要审批就先等结果,不能先做后问。Never 表示不发起相应审批,不代表无限权限;执行失败也不能随意放宽限制。记住:授权不等于业务正确,取消不等于撤销;已经发生的副作用,需要正式撤销或补偿机制,并向用户报告事实。

复述顺序:用户范围 → 审批条件 → 资源限制 → 业务校验 → 失败与恢复边界。

背诵用于抓牢主线。理解自测:用户点击停止后,为什么已经写入工程的数据不一定自动恢复? 仍需通过源码阅读和练习验证掌握,不会因背诵自动标记通关。

核对依据:审批要求与默认策略 · 先审批再执行 · 有限的错误重试分支。

配套音频 · AI 合成语音

先听一遍,再对照源码

普通话讲解,保留关键代码语义、实际操作情境和 GEODYNA 对照。重点区分“是否要问”与“实际允许做什么”。

全长 6:08 · 6 章MP3 · 2.8 MB普通话女声 · 稍慢语速
下载 MP3

点击开始;页面不会自动播放,也不会自动标记课程通关。

点击任一章,从对应位置开始。

    展开音频文字稿 · 听不清时对照看
    声音中的术语,对应代码里的哪个词?

    AI 合成语音;收听位置仅保存在当前浏览器,不跨设备同步。代码以固定快照为准。可下载后用手机播放器离线收听。

    先定位:这一站到底在讲哪一层?

    ToolOrchestrator 位于 Core 的工具执行基础设施中。使用它的执行类工具,将具体请求和运行上下文交给它,由它协调审批、沙箱选择、尝试与受限重试。

    这是一个运行时边界,不是 TUI 的弹窗函数。客户端可以展示审批请求,但是否批准、允许什么范围、实际执行器怎样限制行为,需要沿完整调用链分别验证。

    1. 1收到工具请求与环境上下文
    2. 2计算本次审批要求
    3. 3禁止/需审批/无需本次审批
    4. 4选择适用执行隔离与权限
    5. 5执行一次并观察真实结果
    6. 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,不执行任何真实操作。

    先预测会走哪条分支,再点击按钮查看。

    最容易说错的边界

    常见说法准确表述
    Never 等于全部允许它描述不发起某类审批;实际资源访问仍受环境与工具约束。
    审批通过就不可能破坏工程授权不替代领域校验、事务与正确性验证。
    任何失败都该放宽权限重试只允许在授权范围、特定错误和策略条件内进入相应重试。
    点击停止,所有已执行操作自动撤销取消与撤销是不同机制;需要报告已经发生的事实。

    迁移到你的 GEODYNA 智能体

    以下是设计练习,不代表并行产品线已经实现或通过验收;本次只制作课程,不修改 GEODAMNEW。

    候选危险操作确认应明确:目标工程和对象、即将变更的字段、是否覆盖已有内容、预期影响以及恢复方式。确认时还要防止预览后对象状态变化,使用户批准的是旧内容却执行了新内容。

    真正的写入经正式 Command API、事务、Undo/Redo 和审计路径完成。提示词可以引导模型,但不能替代这些可信执行边界。

    你要设计的点可验证的证据
    确认与实际动作一致保存目标身份和预览版本,提交前重新校验。
    拒绝后无副作用检查工程状态、历史记录和输出文件,不能只检查弹窗是否关闭。
    取消后的事实可说明列出已提交与未执行部分,需要恢复时走正式撤销。
    重复提交可控制用业务命令身份与版本检查验证重复请求不会叠加危险写入。

    产品经理练习:为“覆盖当前算例的某组设置”写一张确认卡和 4 条验收用例,其中必须有拒绝、状态过期和取消。

    先答小测,再看解析

    每题即时反馈,可反复尝试;答对这些题也不会替代你的源码复述。

    1. Skip 一定表示绕过沙箱吗?

    2. Forbidden 分支在协调器中做什么?

    3. AskForApproval::Never 在默认计算里表示什么?

    4. 用户取消时,已提交工程写入是否自动撤销?

    5. 预览后目标版本发生变化,提交时应怎样?

    最后一句话交作业

    请分别解释审批策略、沙箱、领域校验;再说明 Never 为什么不等于无限权限,取消为什么不等于撤销。

    展开参考答案(先自己说一遍)

    审批策略决定何时要求额外批准;沙箱与权限环境约束实际资源访问;领域校验与事务保护工程规则和一致性。Never 表示不发起相应审批,不会自动扩大权限。取消停止后续推进,已提交副作用要由正式撤销或补偿路径处理。

    下一轮再回来时:第三轮追审批等待与取消状态;第四轮再看工具特定策略、不同平台执行器和失败重试的完整条件。