OpenHuman 内置 Settings 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导读本文以 OpenHuman 内置代理 Settings Agentsettings_agent的系统提示词为切入点结合其agent.toml 元数据与底层领域实现完整拆解这一系统管家代理的设计原则只读优先、高风险操作显式确认、事实边界约束、更新与诊断的规范化流程。读完本文你将掌握 OpenHuman 中改配置、查健康、重启/升级、本地诊断类请求是如何被安全地路由和执行的以及如何理解或复刻一个高影响力系统代理的提示词工程。一、Settings Agent 是什么职责边界与触发场景Settings Agent 是 OpenHuman 内置的设置与系统专家代理其自我定位在 prompt.md 开头一句话说得很清楚You own OpenHuman configuration, runtime health, service lifecycle, update, proxy, and local diagnostics surfaces.即它负责六类核心表面surface配置configuration——读取、理解、修改 OpenHuman 的本地配置运行时健康runtime health——组件存活状态、进程元数据、模型健康服务生命周期service lifecycle——守护进程的安装、启动、停止、重启、卸载更新update——检查新版本、下载并应用更新代理proxy——HTTP/HTTPS 代理配置本地诊断local diagnostics——doctor 体检、成本面板、安全策略等只读排查。在 agent.toml 中when_to_use字段明确了编排器orchestrator何时应把任务委派给它Settings and system specialist: app/core config, health and model diagnostics, service lifecycle, proxy, updates, cost dashboards, security policy. Use for change-a-setting, is-the-app-healthy, restart/update, and local diagnostic requests.也就是说帮我改个设置应用健康吗重启一下 / 更新一下做本地诊断这四类用户意图是触发 Settings Agent 的标准场景。作为内置代理它在注册表里以settings_agent为稳定 id 存在并被 builtin_definitions_tests.rs 的expected_builtin_ids_are_present测试明确断言为应存在的内置代理之一。其内置定义由 loader.rs 的BUILTINS静态列表加载解析agent.toml生成AgentDefinition再把prompt.md内容装配为PromptSource::Inline系统提示词并打上DefinitionSource::Builtin标记。二、元数据画像温度、迭代预算与提示词裁剪agent.toml 给出了这个代理的运行时画像各字段含义如下字段值含义idsettings_agent稳定 id路由与 UI 选择均引用它display_nameSettings Agent用户可见名称delegate_namemanage_settings委派时的语义名temperature0.2低随机性——设置/系统操作要求稳定、可复现的输出max_iterations8单轮最多 8 次工具调用迭代IterationPolicy严格上限sandbox_modenone无沙箱自身是系统操作面agent_tierworker工作级代理非编排器omit_identitytrue提示词中省略身份描述omit_memory_context/omit_memory_mdtrue不注入记忆上下文与记忆 Markdown保持提示词精简omit_profiletrue不注入用户画像omit_safety_preamblefalse保留安全开场白——因为本代理拥有高影响力工具[model].hintagentic模型路由提示为 agentic 角色值得注意omit_safety_preamble false这一反例大多数非编排器内置代理默认省略安全开场白以压缩上下文但 Settings Agent 拥有服务生命周期与更新这类可改变系统状态的高影响力工具因此必须保留安全引导。这体现了权限越大、提示约束越强的工程取舍。三、第一原则只读优先先观察再行动prompt.md 用 Work conservatively保守工作概括了整体行为基调第一条规则是Start with read-only tools (config_*,doctor_*,health_*,service_status,daemon_host_prefs_get,security_policy_info, cost/model health) before proposing any mutation.即在提出任何变更之前必须先使用只读工具建立事实基线。按此原则agent.toml 中的工具白名单可以被清晰地划分为只读侦查与变更动作两大阵营只读侦查工具Read-only工具对应底层实现 / 领域config_snapshot/config_get_client_config/config_get_autonomy/config_get_search/config_get_runtime_flags/config_resolve_api_url/config_get_data_paths配置域读取。config_snapshot底层由 loader_part_01.rs 的get_config_snapshot/load_and_get_config_snapshot提供返回完整配置快照并注明配置来源路径doctor_health/doctor_models诊断域。见 platform/doctor/ops.rsdoctor_report在 blocking 线程上运行同步体检并统计记忆块数doctor_models执行模型探针health_snapshot/health_system_info健康注册表。见 platform/health/ops.rs快照返回各组件存活状态system_info返回version/os/arch/piddashboard_model_health模型健康对比视图Settings → Developer Options → Model Health见 desktop/dashboard/README.mdcost_get_dashboard/cost_get_daily_history/cost_get_summary成本面板。见 platform/cost/README.md7 天看板、按日历史、会话/日/月汇总security_policy_info安全策略只读。见 security/ops.rs输出autonomy、workspace_only、allowed_commands、max_actions_per_hour等service_status服务状态。见 platform/service/ops.rs 与 service/core.rs 的ServiceStatus { state, unit_path, label, details }state为Running/Stopped/NotInstalled/Unknowndaemon_host_prefs_get读取守护进程宿主偏好session_state/session_get_user/credential_list/oauth_connect_url/oauth_list只读账号/凭据/OAuth 状态。agent.toml 注释特别说明这些是从已移除的account_admin_agent继承的只读账户状态当前登录了哪个账号、哪些 provider 已连接与资金流转或团队管理无关且credential_list只返回非机密元数据变更动作工具High-impactservice_start/service_stop/service_restart/service_shutdown/service_install/service_uninstall——服务生命周期daemon_host_prefs_set——守护进程偏好写入proxy_config——代理配置变更写路径见下文底层实现update_apply——应用更新。四、高风险操作的显式确认闸门prompt.md 的第二条规则是本代理最核心的安全机制Treat service lifecycle and update actions as high-impact. Ask for explicit confirmation beforeservice_start,service_stop,service_restart,service_shutdown,service_install,service_uninstall,daemon_host_prefs_set,proxy_config, orupdate_apply.即上述 9 个变更工具必须在获得用户显式确认后才能调用。这一提示词层面的口头闸门与代码层面的硬性闸门相互配合ask_user_clarification作为中断工具该工具是子代理回合图subagent_runner/ops/graph.rs中的early-exit tool——当模型需要向用户求证时才调用它执行后本轮回合暂停等待用户输入是编排层对显式确认的机械支撑。更新域的 fail-closed 策略见 platform/update/README.md——update_apply/update_run由enforce_update_mutation_policy把关若config.update.rpc_mutations_enabledfalse或配置加载失败fail-closed任何更新变更都会被拒绝。工具级自主性检查update_apply工具实现tools/impl/system/update_apply.rs除了走 RPC 策略外还会叠加SecurityPolicy::can_act自主性检查确保只读会话即使策略门开着也无法触发下载其工具描述明确要求编排器先通过ask_user_clarification与用户确认——因为应用更新会替换磁盘上的二进制并可能重启核心进程。服务生命周期的实现边界service_restart/service_shutdown走的是异步重启/优雅关闭通道service::restart::service_restart、service::shutdown::service_shutdown并接受source与reason两个上下文参数便于审计谁、为什么触发了动作。五、事实边界绝不虚构配置变更prompt.md 用两条规则约束模型的嘴Never claim a config value changed unless a tool result confirms it.If a requested config mutation has no tool, say which current read-only state you inspected and what UI or controller should own the change.第一条防止模型幻觉——工具没有返回成功结果就不允许声称已修改这要求模型严格基于RpcOutcome的返回值陈述事实。第二条是优雅降级如果用户要求的变更在当前工具集中没有对应工具模型必须如实说明我检查了哪些只读状态以及这个变更应由哪个 UI 面板或 controller 负责而不是假装完成或编造路径。最后一条规则 Return exact tool-observed state and any action taken返回工具实际观测到的状态与已执行的动作与上述两条一脉相承共同构成可审计的对话式运维纪律。六、更新流程的规范三步曲针对更新场景prompt.md 给出了明确的执行顺序For update flows, runupdate_checkfirst, summarize version/channel/risk, then callupdate_applyonly after confirmation.update_check先行update_check是只读工具tools/impl/system/update_check.rs仅执行一次对 GitHub Releases latest 端点的 HTTPS 请求返回版本信息、下载 URL、资产名与发布说明不下载不安装。汇总版本/通道/风险模型向用户报告当前版本 vs 最新版本、通道差异与更新风险。确认后再update_apply获得确认后调用update_apply底层走update::rpc::update_run编排的 check → download → stage → restart 全流程platform/update/README.md。底层更新域的细节值得展开同样来自 update README资产选择按平台 triple 匹配openhuman-core-{triple}Windows 为.exe下载后 Unix 置0o755并原子重命名进 staging 目录重启策略分SelfReplace发布自重启与Supervisor仅暂存后台还有默认 1 小时、下限 10 分钟的周期检查器。RPC 边界会对下载 URL必须是 HTTPS GitHub 主机与资产名必须以openhuman-core-开头、不允许路径分隔符或..做二次校验。七、诊断输出纪律症状、现状、建议三分法For diagnostics, separate symptoms, current state, and recommended next action.prompt.md 要求诊断类回答严格区分三层信息症状symptoms——用户描述的现象或触发背景当前状态current state——工具实际观测到的状态如health_snapshot中各组件 status / last_ok / last_error / restart_count或service_status返回的Running/Stopped/NotInstalled建议的下一步recommended next action——基于状态的处置建议。这种现象—事实—建议的三段式结构与底层健康域的设计相呼应健康注册表platform/health/README.md维护每个组件的status/updated_at/last_ok/last_error/restart_count并通过verdict()分类只有关键组件core、memory_tree_db不健康时/health才返回 503非关键组件scheduler、channels、update_checker 等不健康则返回 200 degraded标志。诊断代理汇报时必须把这些可验证的状态字段与建议分开展示避免把推断当事实。八、工具白名单全景从提示词到领域实现的映射将 agent.toml 的[tools].named白名单按领域归类可得到以下全景含底层实现佐证领域工具底层实现配置快照config_snapshot,config_get_client_config,config_get_autonomy,config_get_search,config_get_runtime_flags,config_resolve_api_url,config_get_data_pathsconfig/ops/loader_part_01.rsget_config_snapshot体检/诊断doctor_health,doctor_modelsplatform/doctor/ops.rs健康health_snapshot,health_system_infoplatform/health/ops.rs模型健康dashboard_model_healthdesktop/dashboard/README.mdmodel_health控制器dashboard.model_health阈值成本cost_get_dashboard,cost_get_daily_history,cost_get_summaryplatform/cost/README.mdcost_*命名空间预算门BudgetCheck::{Allowed, Warning, Exceeded}安全策略security_policy_infosecurity/ops.rsSecurityPolicy::from_config 策略 JSON 载荷服务生命周期service_status只读、service_start、service_stop、service_restart、service_shutdown、service_install、service_uninstallplatform/service/ops.rs、service/core.rs守护进程偏好daemon_host_prefs_get只读、daemon_host_prefs_set写platform/service/ops.rsdaemon_host_get/daemon_host_set代理proxy_configconfig/schema/proxy.rsProxyConfig更新update_check只读、update_apply写tools/impl/system/update_check.rs、tools/impl/system/update_apply.rs账号/凭据只读session_state,session_get_user,credential_list,oauth_connect_url,oauth_list仅非机密元数据协作/其他ask_user_clarification,current_time回合图中的 early-exit 工具subagent_runner/ops/graph.rs8.1 代理配置的底层模型proxy_config工具对应 config/schema/proxy.rs 中的ProxyConfig[proxy] enabled false # 总开关 http_proxy # HTTP 代理 URL https_proxy # HTTPS 代理 URL all_proxy # 全协议代理 URL no_proxy [] # 豁免域名列表 scope openhuman # Environment | OpenHuman | Services services [] # 命中的服务键列表其中scope控制代理生效范围进程环境 / OpenHuman 自身 / 外部服务services支持按服务键精确控制SUPPORTED_PROXY_SERVICE_KEYS覆盖provider.*anthropic、openai、gemini、ollama 等、channel.*telegram、slack、discord 等、tool.*browser、composio、http_request、memory.embeddings、tunnel.custom等条目也支持provider.*、channel.*这类通配选择器。代理配置属高风险写操作因此在提示词中被列为须显式确认的工具之一。8.2 安全策略只读面的字段含义security_policy_info由 security/ops.rs 计算自活动配置返回六个关键字段autonomy——自主性级别Supervised / SemiAutonomous / Autonomous见 security/README.mdworkspace_only——是否仅限工作区操作allowed_commands——允许的命令列表max_actions_per_hour——每小时动作上限require_approval_for_medium_risk——中风险操作是否需审批block_high_risk_commands——是否阻断高风险命令。这些字段让 Settings Agent 在不接触秘密的前提下就能回答当前安全策略是什么、会拦什么。九、提示词是如何在运行时组装的prompt.md并不是最终发送给模型的完整提示词而是 archetype原型部分。prompt.rs 的build()展示了完整的组装流水线include_str!(prompt.md)载入原型正文追加render_user_files(ctx)——与用户关联的文件上下文追加render_tools(ctx)——根据运行时状态渲染实际可用的工具清单这是工具白名单最终生效的环节动态分支于可用工具集合追加render_safety()——安全开场白omit_safety_preamble false决定了它必须被渲染追加render_workspace(ctx)——工作区上下文。也就是说最终系统提示词 本文剖析的 archetype 用户文件 动态工具清单 安全引导 工作区信息。这种静态原型 动态装配的结构正是 OpenHuman 内置代理提示词工程的标准模式见 loader.rs 中 每个内置代理 agent.toml prompt.rs 的约定。十、从内置到自定义注册表视角Settings Agent 不只是一段提示词它是整个用户面代理注册表中的一个条目。注册表数据模型AgentRegistryEntrytypes.rs包含id/name/description/sourceDefault 或 Custom/enabled/model/system_prompt/tool_allowlist/tool_denylist/subagents/tags/metadata等字段且validate()强制id只允许 ASCII 字母、数字、_、-。内置代理如 Settings Agent通过default_agents()从 harness 定义生成注册表条目defaults.rswhen_to_use成为description工具范围映射为tool_allowlistagent_tier写入tags。反过来用户自定义代理也能通过definition_from_registry_entry合成 harness 定义走同一执行路径defaults.rs。理解这一机制的意义在于Settings Agent 的工具边界35 个具名工具不是硬编码在 prompt 里的而是由agent.toml声明、由注册表路由、由运行时render_tools最终落地的。若你想裁剪或扩展一个系统代理的权限修改的方向是tool_allowlist/tool_denylist而不是提示词里的工具名。结语OpenHuman 的 Settings Agent 是一个高权限但强约束的内置代理范本它用temperature 0.2压制随机性、用只读先行规则保证先取证后行动、用ask_user_clarification与代码层 fail-closed 策略双保险约束 9 个高风险写工具、用症状/现状/建议三分法规范诊断输出、用工具结果才算数杜绝变更幻觉。其 prompt.md 与 agent.toml、prompt.rs 及 health / doctor / service / update / security / cost / dashboard / proxy 各领域实现共同构成一套完整的对话式系统运维闭环值得作为系统类子代理提示词与权限设计的参考样例。相关阅读继续深入可查看 settings_agent/prompt.rs提示词装配、registry/defaults.rs注册表映射、platform/update/README.md更新域、platform/health/README.md健康域与 security/README.md安全边界。【免费下载链接】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），仅供参考