OpenHuman 工具执行超时机制解析tool_timeout模块的运行时可变超时策略【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman导读OpenHuman 是一个面向 Mac、Windows、Linux 的开源个人 AI本地优先的记忆、Agent 编排与深度研究。在 Agent 长时间运行的过程中工具调用如网络请求、MCP 调用、shell 脚本执行可能因外部服务挂起而拖垮整个会话因此需要一个进程级、可运行时修改的墙钟wall-clock超时策略。本文围绕 src/openhuman/tools/timeout/README.md 展开深入解析tool_timeout模块的实现、配置项、解析顺序与使用场景。读完本文你将掌握如何通过[agent].agent_timeout_secs配置与OPENHUMAN_TOOL_TIMEOUT_SECS环境变量控制工具执行超时理解环境变量始终优先的覆盖语义以及脚本工具shell/node_exec/npm_exec为何默认无超时运行。模块定位与核心设计tool_timeout是 OpenHuman 中专门负责工具执行超时的模块其核心目标可概括为解析并持有单一的、有界的超时值秒与Duration两种形态该值运行时可变UI 通过config.update_agent_settingsRPC 即可修改无需重启 core且修改在下一次工具调用时生效提供一个进程全局的AtomicU64作为运行时存储首次读取时惰性初始化从环境变量/默认值解析将解析与解析逻辑保持为纯函数、可测试与全局状态变更隔离。从源码看模块文件 src/openhuman/tools/timeout/mod.rs 是整个模块的全部实现常量、环境变量解析、纯解析函数、原子运行时值、setter、公共访问器以及内联单元测试。超时值的解析顺序模块定义了明确的优先级最高优先级在前OPENHUMAN_TOOL_TIMEOUT_SECS环境变量——操作者operator覆盖。当设置为合法值1..3600时始终生效只要该变量存在配置推送config push就会被忽略。持久化配置值[agent].agent_timeout_secs——由set_tool_timeout_secs在启动时来自core::jsonrpc::register_domain_subscribers即始终开启的 core 启动路径以及每次config.update_agent_settingsRPC 时推入。内置默认值DEFAULT_TIMEOUT_SECS120 秒。实现层面resolve_effective(config_secs, env_raw)mod.rs正是按此顺序解析先看环境变量是否有合法值有则返回环境变量值否则将配置值经过parse_tool_timeout_secs有界化后返回。而current_secs()mod.rs在原子值为 0即尚未播种的哨兵值时用resolve_effective(DEFAULT_TIMEOUT_SECS, env)播种并发首次读取会收敛到同一个种子值。常量定义与取值范围模块定义了以下公开常量mod.rs常量值含义DEFAULT_TIMEOUT_SECS120默认工具执行超时秒MIN_TIMEOUT_SECS1最小可接受超时。0意味着禁用超时因此被拒绝并回退到默认值MAX_TIMEOUT_SECS3600最大可接受超时1 小时防止拼写错误导致挂起的工具无限期卡住会话SANDBOX_UNBOUNDED_CAP_SECS86_400沙箱后端的有效无限上限24 小时。脚本工具在原生路径上真正无超时运行但沙箱路径要求有限 deadline当未显式请求timeout_secs时用此慷慨上限替代ENV_VAROPENHUMAN_TOOL_TIMEOUT_SECS操作者覆盖环境变量名所有候选值都会被限制到1..3600秒缺失、非数值、零、负数或越界输入一律回退到 120 秒默认值。公共 API 面模块对外暴露了完整的函数接口parse_tool_timeout_secs(raw: Optionstr) - u64纯解析函数将有界值限制到1..3600否则返回默认值。set_tool_timeout_secs(config_secs: u64) - u64将配置源值推入运行时原子尊重环境变量覆盖返回实际存储的有效值。启动时和每次配置更新时都会调用。env_override_active() - bool当OPENHUMAN_TOOL_TIMEOUT_SECS设置为合法覆盖值时返回true此时 UI 变更被忽略该状态会暴露给设置面板。tool_execution_timeout_secs() - u64读取当前有效超时值秒每次调用都会重新读取。tool_execution_timeout_duration() - Duration同一有效值以Duration形态返回。explicit_call_timeout_secs(requested: Optionu64, cap: u64) - Optionu64为默认无界的脚本工具解析显式的每次调用超时。None/Some(0)⇒None无界运行任意正数都会钳制到MIN_TIMEOUT_SECS..cap。调用方传入自己的上限shell用MAX_TIMEOUT_SECSnode_exec/npm_exec用1800。explicit_call_timeout_duration(requested: Optionu64, cap: u64) - OptionDuration同一逻辑的Duration形态None表示无界。另有内部常量TOOL_TIMEOUT_GRACE_SECS 5用于为显式预算加上宽容余量见下文。脚本工具默认无界运行issue #4023这是本模块一个关键设计决策全局超时只约束非脚本工具——挂起的网络/MCP 调用必须保持有界而脚本工具shell、node_exec、npm_exec默认没有 deadline一次构建、求解器或测试运行合法地需要数分钟不应被默认上限强制杀死。这些脚本工具暴露了每次调用的timeout_secs参数并通过Tool::timeout_policy返回ToolTimeout::Unbounded未提供时或ToolTimeout::Secs(n)提供时。OpenHuman 工具适配器将Unbounded映射为完全不包tokio::time::timeout将Secs(n)映射为钳制后的 deadline加上 5 秒宽容余量以便工具自身的内部超时真正负责杀子进程的超时先触发。沙箱后端要求有限 deadline因此在无界场景下用SANDBOX_UNBOUNDED_CAP_SECS24 小时替代——足够长不杀死合法长任务又足够有限以最终回收卡住的沙箱进程。resolve_tool_deadlinemod.rs是这一策略的核心实现返回(deadline, timeout_secs)二元组Inherit使用全局配置驱动的超时有限 deadlineSecs(req)将请求钳制到1..3600实际 deadline 为s 5秒timeout_secs报告的是未加余量的预算Unbounded返回(None, 0)——无 deadline工具运行到完成。配置项与运行时语义配置 TOML[agent].agent_timeout_secs整数秒合法范围1..3600默认120。可在Settings → Agent OS access → Action timeout中实时编辑或通过config.update_agent_settingsRPC 修改。OPENHUMAN_TOOL_TIMEOUT_SECS环境变量操作者覆盖范围相同。合法时覆盖配置值非法值被忽略配置值仍生效。在 schema 定义中src/openhuman/config/schema/agent.rs该字段的文档注释明确说明其作用于单个工具/动作执行的墙钟超时以及每 Agent 的委派聊天调用并提及 issue #3100——运行大型本地模型的用户无需编辑配置文件即可延长超时。配置应用与读取src/openhuman/config/ops/agent.rs 中的apply_agent_settings展示了完整的运行时更新路径校验agent_timeout_secs是否在MIN_TIMEOUT_SECS..MAX_TIMEOUT_SECS范围内越界则拒绝并返回错误信息持久化配置config.save()调用set_tool_timeout_secs将新值推入运行时原子——无需重启 core下一次工具调用即生效除非环境变量覆盖生效此时推送为 no-op返回更新后的配置快照。get_agent_settings则返回agent_timeout_secs、effective_timeout_secs、env_override、min_timeout_secs、max_timeout_secs让 UI 能在环境变量覆盖时向用户解释此控件当前无效果。前端设置面板如 app/src/components/settings/panels会显示类似 The OPENHUMAN_TOOL_TIMEOUT_SECS environment variable is overriding this setting, so changes here have no effect until it is unset. 的提示见 app/src/lib/i18n/en.ts。启动路径播种src/core/jsonrpc.rs 的register_domain_subscribers在始终开启的 core 启动路径其非门控的INFRA: Once块中调用set_tool_timeout_secs(config.agent.agent_timeout_secs)见 src/core/jsonrpc.rs确保无 channel / 仅 web-chat 的 core也能获得配置的超时值issue #5027。相关测试见 src/core/jsonrpc_tests.rs。使用方调用链src/openhuman/agent/tinyagents/tools.rsOpenHuman 工具通过execute_with_options执行应用每个工具的Tool::timeout_policyInherit使用tool_execution_timeout_secs()Secs(n)使用钳制值加宽容余量Unbounded无 deadline 运行。src/openhuman/tools/impl/system 下的shell.rs、node_exec.rs、npm_exec.rs脚本工具默认无界支持显式timeout_secs。src/openhuman/agent/tools/delegate.rs用tool_execution_timeout_secs()为委派 provider 的聊天调用设界。src/openhuman/config/ops.rsapply_agent_settings持久化后调用set_tool_timeout_secsget_agent_settings上报effective_timeout_secs/env_override。src/core/jsonrpc.rsregister_domain_subscribers在启动时播种运行时值。src/openhuman/agent/harness/harness_gap_tests.rs固定parse_tool_timeout_secs的默认值/边界行为。边界行为与易错点以下是模块文档明确列出的注意事项也是实际使用中容易踩坑的地方值在每次工具调用时新鲜读取配置变更在下一次工具调用生效一个已在进行中的tokio::time::timeout保持其捕获的 deadline。0被刻意拒绝0本意可能是禁用超时但模块选择拒绝并回退到默认值而不是禁用。存在但非法的环境变量不算覆盖非数值 /0/ 越界的环境变量值视为无覆盖配置值仍生效只有合法的环境变量值才能覆盖。默认值120 秒必须与前端镜像的超时保持一致见 app/src/utils/config.ts 中的TOOL_TIMEOUT_SECS同样默认 120、最大 3600非法值回退到默认值。从单元测试 src/openhuman/tools/timeout/mod_tests.rs 可以完整验证以上行为环境缺失/非数值/零/越界/负数均回退默认值第 4-37 行边界值1与3600被接受第 40-43 行env_override_takes_precedence_over_config验证环境变量优先第 51-54 行config_value_used_when_env_absent_or_invalid验证非法环境变量被忽略第 57-65 行explicit_call_timeout_enforces_and_clamps_request验证显式调用超时的钳制行为第 83-103 行。依赖与设计取舍模块依赖极简仅log用于配置推送时的 debug 跟踪其余只用标准库std::sync::atomic::AtomicU64、std::time::Duration、std::env。resolve_tool_deadline在 tinyagents 迁移期间issue #4249从退役的 legacyengine::tools模块移入此处与它使用的超时常量放在一起。从源码结构看这种解析纯函数 全局原子的分离设计可以推断出几个明确意图解析逻辑可被单元测试无竞态地全覆盖全局状态只承载最终有效值setter 幂等可安全地在启动与每次配置更新时重复调用环境变量覆盖作为操作者级安全网始终优先于用户级配置防止 UI 误操作绕过运维约束。总结tool_timeout是 OpenHuman 工具执行链路中一个小而精的守护模块它以1..3600秒的有界窗口统一了工具执行超时用环境变量 配置 默认值的优先级保证操作者控制权用运行时可变原子让 UI 修改即时生效并用脚本工具默认无界、显式timeout_secs按需设限的差异化策略兼顾了长任务与挂起防护。理解这一机制是正确调优 OpenHuman Agent 行为、排查工具为何被杀死或工具为何无限运行类问题的前提。【免费下载链接】openhumanOpenHuman is an open source personal AI for Mac, Windows and Linux — local-first memory, agent orchestration, and deep research.项目地址: https://gitcode.com/GitHub_Trending/op/openhuman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考