其它内置工具 · 计划、提问、权限与搜索

其它内置工具 · 计划、提问、权限与搜索

前面几篇讲完了“重”的工具。剩下的内置工具体量都不大，却覆盖了 agent 的几种基本需要：跟踪进度、向人提问、申请权限、感知时间与上下文余量、找工具、看图、上网。它们大多在 add_core_utility_tools（codex-rs/core/src/tools/spec_plan.rs:1148）里登记，tool_search 与托管的 web_search 在收尾阶段加入，另有几个来自扩展；下面逐个看出现条件、参数与返回。多 agent 协作工具留给多 agent。用户这一侧能碰到的多半只是开关：web_search 的几种取值见手册配置项速查，request_user_input 所在的 Plan 模式用 /plan 或 Shift+Tab 切换（见斜杠命令）。

一张总表

update_plan：只发事件的计划工具

计划工具的实现几乎只有一件事：把参数原样变成一个 PlanUpdate 事件，交给界面渲染成清单。模型拿到的永远是一句 Plan updated。它和 Plan 模式是两回事，在 Plan 模式里调用反而会被拒绝：

        if turn.mode() == ModeKind::Plan {
            return Err(FunctionCallError::RespondToModel(
                "update_plan is a TODO/checklist tool and is not allowed in Plan mode".to_string(),
            ));
        }

        let args = parse_update_plan_arguments(&arguments)?;
        session
            .send_event(turn.as_ref(), EventMsg::PlanUpdate(args))
            .await;

        Ok(boxed_tool_output(PlanToolOutput))

（codex-rs/core/src/tools/handlers/plan.rs:87）

每个计划项的 status 只能是 pending、in_progress、completed，工具描述要求同一时间最多一项 in_progress。tools.update_plan.enabled 不写就是关，这是 resolve_update_plan_enabled 用 is_some_and 定下的默认值。

向人要东西：提问、权限与安装

这三个工具的共同点是处理器发出请求后挂起，等前端（终端界面或其它 app-server 客户端）回应，再把回应序列化成 JSON 交还模型。

request_user_input 的 questions 里每个问题要有 id、header（不超过 12 个字符）、question 与 2 到 3 个 options，推荐项放第一个并在标签后加 “(Recommended)”；“Other” 选项由客户端自动补上，模型不用写。处理器的检查依次是：

        if turn.session_source.is_non_root_agent() {
            return Err(FunctionCallError::RespondToModel(
                "request_user_input can only be used by the root thread".to_string(),
            ));
        }

        let mode = turn.collaboration_mode().mode;
        if let Some(message) = request_user_input_unavailable_message(mode, &self.available_modes) {
            return Err(FunctionCallError::RespondToModel(message));
        }

        let args: RequestUserInputToolArgs = parse_arguments(&arguments)?;
        let args = normalize_request_user_input_tool_args(args)
            .map_err(FunctionCallError::RespondToModel)?;
        let args = RequestUserInputArgs {
            questions: args.questions,
            is_blocking: mode == ModeKind::Plan,
            auto_resolution_ms: None,
        };

（codex-rs/core/src/tools/handlers/request_user_input.rs:67）

子 agent 不能直接问人；可用的协作模式只有 Plan（ModeKind::allows_request_user_input 只认 Plan，默认模式要等开发中的 default_mode_request_user_input）；缺选项的问题直接退回。返回的是 {"answers": {"<问题 id>": {"answers": [...]}}} 形式的 JSON。guardian_approval 特性（默认开）打开时，用户的回答还会作为“已核实的答复”（VerifiedAnswer）留存进上下文，供自动审查参考。模型目录还可以声明一个异步版本 request_user_input_async，两者都登记为 DirectModelOnly，不进 Code mode。

request_permissions 让模型在沙箱之内申请额外的读写路径或联网权限，参数里的相对路径按所选环境的工作目录解析，一项都没有就报错。回应里带着用户实际批准的子集和范围（turn 或 session），工具描述写明批准的权限会自动作用于本轮（或整个会话）后续的 shell 类命令。审批的细节见审批流程。

插件安装建议由 tool_suggest（默认开，还要求 apps 与 plugins）控制，而且只有在 built_tools 找到了可推荐的候选时才登记。有两种呈现：一种是先调 list_available_plugins_to_install 列候选、再调 request_plugin_install 发请求；另一种是候选已经以 <recommended_plugins> 列表的形式放进上下文，只剩后一个工具。工具描述反复叮嘱，只在用户明确点名要用某个插件或连接器、手头又没有能用的工具时才调用，request_plugin_install 还要求不要与其它工具并行调用。请求以一次 elicitation 呈现给用户，结果 JSON 里有 completed、user_confirmed 等字段；目前在 codex-tui 里请求安装插件（连接器不受影响）会直接回 plugin install requests are not available in codex-tui yet。

时间与上下文余量

这两组工具都要靠模型目录或开发中的特性打开。时钟工具放在 clock 命名空间下：curr_time 返回 It is 2026-09-29 08:00:00 UTC. 这样一句话，读时钟失败默认是 Fatal（开启 nonfatal_clock_read_errors 后降为普通错误）；sleep 最长 12 小时，有新输入进来会提前结束。上下文预算工具由 token_budget 打开：

    if features.enabled(Feature::TokenBudget) {
        registry.add_with_exposure(NewContextWindowHandler, ToolExposure::DirectModelOnly);
        registry.add(GetContextRemainingHandler);
    }

    let current_time_reminder_enabled = features.enabled(Feature::CurrentTimeReminder);
    let model_has_clock = context
        .model_info
        .experimental_supported_tools
        .iter()
        .any(|tool| tool == "clock");
    if current_time_reminder_enabled || model_has_clock {
        registry.add(CurrentTimeHandler);
    }

（codex-rs/core/src/tools/spec_plan.rs:1220）

get_context_remaining 回一句 You have N tokens left in this context window.；处理器文件叫 new_context_window.rs，但工具名是 new_context，它只是在会话状态里记一个请求，回复模型“新窗口会在不做摘要的情况下开始”，真正的切换由主循环在下一步处理（见上下文压缩）。

看图与上网

view_image 先检查模型支不支持图片输入，不支持就直接退回；然后从执行环境的文件系统读文件、解码校验，作为一个 InputImage 内容项（data URL）返回。模型支持原图细节时多一个 detail 参数，high 是默认的缩放版，original 保留原始分辨率。

网页搜索有两套。托管的 web_search 是 Responses API 的内置工具，由 OpenAI 服务端执行，Codex 只负责在请求里声明它，create_web_search_tool 把配置里的模式翻译成两个开关：

    let (external_web_access, indexed_web_access) = match options.web_search_mode {
        Some(WebSearchMode::Cached) => (false, None),
        Some(WebSearchMode::Indexed) => (true, Some(true)),
        Some(WebSearchMode::Live) => (true, None),
        Some(WebSearchMode::Disabled) | None => return None,
    };

（codex-rs/core/src/tools/hosted_spec.rs:15）

cached 不允许实时抓取，indexed 只抓已被索引的页面，live 完全放开；模型目录的 web_search_tool_type 为 TextAndImage 时还会声明可以返回图片结果。另一套是扩展 codex-rs/ext/web-search 提供的 web.run，由 Codex 在客户端调用搜索接口，一次调用可以组合 search_query、image_query、open、click、find、screenshot 以及天气、金融、体育等命令；它在 Responses Lite 模型上，或开启了开发中的 standalone_web_search 时启用，一旦启用，托管的 web_search 就不再声明。图片生成 image_gen.imagegen 同样来自扩展（codex-rs/ext/image-generation），要求特性开启、非免费账号、提供方支持、模型接受图片输入，并且走 OpenAI 认证。

tool_search：把延迟工具取回来

tool_search 的 spec 类型是 Responses API 的 tool_search，execution 为 client，由 Codex 自己执行。参数只有 query 与 limit（默认 8，传 0 报错）。处理器用 BM25 在所有延迟工具的检索文本上打分。检索文本默认由工具名（包括把下划线换成空格的写法）、描述和参数 schema 里的字段名与描述拼成，MCP 工具另有一套，还会加上服务器名、工具标题、连接器名与插件名；命中的工具按命名空间合并后返回。返回的定义被专门改过：

    for tool in &mut namespace.tools {
        match tool {
            ResponsesApiNamespaceTool::Function(tool) => {
                tool.defer_loading = Some(true);
                tool.output_schema = None;
                tool.parameters.mcp_input_schema_max_bytes = None;
            }
            ResponsesApiNamespaceTool::Custom(tool) => {
                tool.defer_loading = Some(true);
            }
        }
    }

（codex-rs/tools/src/tool_search.rs:97）

每个工具都打上 defer_loading，去掉输出 schema，作为 tool_search_output 条目写回历史，下一次采样时模型就能直接调用它们。处理器对象按注册表内容缓存（ToolSearchHandlerCache），MCP 工具的定义不变时 BM25 索引也不必重建。它的描述里列出了所有来源（MCP 服务器名或连接器名及其说明，总长不超过 512 KiB），开启开发中的 deferred_tool_world_state 后，这份清单改由上下文注入。

和《从 LLM 到 Coding Agent》对照

MCP 与工具懒加载里的 search_tools 元工具，在 Codex 里就是 tool_search，而且把“加载完整 schema”做成了 Responses API 的原生条目。权限系统讲的是 agent 被动地等审批，request_permissions 则让模型主动申请，把“我需要更多权限”变成一次正式的工具调用。update_plan 与 request_user_input 都属于工具抽象里说的“给人看”的那一半：前者只产生界面事件，后者把人拉进回路。

上一篇：MCP 工具调用 · 连接管理与工具目录 · 下一篇：Code mode · 让模型写 JavaScript 编排工具