Open SWE 模型、Profile 与指令体系全解从模型注册表到线程快照的完整决策链【免费下载链接】open-sweAn Open-Source Asynchronous Coding Agent项目地址: https://gitcode.com/GitHub_Trending/op/open-swe在 Open SWE 中一次 hosted agent 运行的启动远不止选一个模型那么简单系统必须在构建模型之前解析出一个合法且可构造的(model_id, effort)组合并确定一个线程级稳定、仓库级有效的指令值。而触发用户的身份、凭据、PR 偏好与个人指令则被刻意地在每条消息上重新求值。本文基于仓库文档 openwiki/concepts/models-profiles-instructions.md结合 agent/utils/model.py、agent/dashboard/options.py、agent/dashboard/team_settings.py 等源码完整讲解模型注册表、团队/Profile/线程三层优先级、供应商推理参数构造、LangSmith Gateway 路由以及四类指令源的权威层级。读完你将掌握如何在 Open SWE 中配置默认模型与 effort、为什么线程快照能让多参与方长生命周期线程稳定运行以及如何安全地新增或替换模型。模型注册表与过期选择的恢复SUPPORTED_MODELS可选的模型注册表SUPPORTED_MODELS是系统精选可选项的唯一模型注册表定义于 agent/dashboard/options.py。每一项ModelOption是一个TypedDict包含id带供应商前缀的模型标识如anthropic:claude-opus-5、openai:gpt-6-astralabel展示名如Opus 5、GPT-6 Astraefforts该模型允许的推理 effort 列表default_effort未显式指定时的默认 effortsupports_images是否支持多模态图片输入can_be_default可选是否允许保存为默认模型context_window可选运行时填充上下文窗口大小。当前注册表中的代表性条目节选自 options.py模型 ideffortsdefault_effort图片备注anthropic:claude-opus-5low / medium / high / xhigh / maxhigh✅主力推理模型anthropic:claude-haiku-4-5nonenone✅不提供推理参数anthropic:claude-fable-5-1low / medium / high / xhigh / maxhigh✅can_be_default: false受 ZDR 门控openai:gpt-6-astralow / medium / high / xhigh / maxxhigh✅openai:gpt-5.6-solnone / low / medium / high / xhighxhigh✅双供应商部署时的默认 OpenAI 模型google_genai:gemini-3.8-flashminimal / low / medium / highmedium✅Gemini 3 家族使用thinking_levelfireworks:accounts/fireworks/models/kimi-k3low / high / maxhigh❌K3 始终推理拒绝mediumfireworks:accounts/fireworks/models/deepseek-v4-pronone / low / medium / high / xhigh / maxhigh❌fireworks:accounts/fireworks/models/glm-5p3none / high / maxhigh❌fireworks:accounts/fireworks/models/glm-5p3-flashlow / high / maxhigh✅路由 fast 档默认关键设计点effort 并非全局枚举。不同模型允许的取值完全不同——Kimi K3 只接受low/high/maxHaiku 只接受noneGemini 用minimal到high。因此任何选择都必须通过两个校验函数options.pymodel_supports_effort(model_id, effort)校验(model_id, effort)组合合法性model_supports_images(model_id)校验模型是否支持多模态输入。SUPPORTED_MODEL_IDS是注册表的成员集合用于解析期判断FABLE_MODEL_IDS与NON_DEFAULT_MODEL_IDS则分别用于 Fable 门控与不可设为默认约束。/options 端点只读的注册表视图Dashboard 的/options响应不会修改注册表。它返回的是拷贝记录并做了三类增强见 options.py 的models_with_profile_context_windows优先使用显式的 Codex 上下文窗口覆盖CODEX_CONTEXT_WINDOW_OVERRIDES如 GPT-6 Astra 为 272,000 token其次读取 LangChain 供应商 profile_get_default_model_profile中的max_input_tokens最后兜底一个小型回退表_PROFILE_CONTEXT_WINDOW_FALLBACKS如 Kimi K3 为 1,048,576 token。同时当工作区开关关闭时会移除 Fable 选项返回的默认值同样经过门控保证界面上永远不会推荐一个被禁用的模型。部署级默认与失效恢复default_model_pair()options.py是部署层的最终兜底读取环境变量LLM_MODEL_ID与LLM_REASONING_EFFORT未设置时回退到凭据敏感的内建默认若只配置了ANTHROPIC_API_KEY则用anthropic:claude-opus-5否则用openai:gpt-5.6-sol默认 effort 为mediumoptions.py所选默认必须是受支持、可设为默认且支持其 effort 的模型否则直接抛出ValueError而不是构造任意模型本地开发启动时还会额外校验默认模型所需凭据validate_local_dev_llm_config见 agent/utils/model.py且仅当DASHBOARD_BASE_URL显式为http://localhost前缀时才执行避免阻塞刚部署尚无 URL 的 LangGraph Platform 环境。当一个选择从注册表中掉出时处理方式取决于它是否被显式列入DEPRECATED_MODEL_IDSoptions.py非废弃 idprovider_fallback_pairoptions.py会选择同一供应商上最新的受支持模型优先保持同一 Claude 家族在支持的情况下保留原 effort包括把 Gemini 的none映射为minimal否则使用回退模型的默认 effort。未知供应商则返回None交还上层决策。废弃 id被排除在上述恢复路径之外直接让位给团队或部署默认。目前DEPRECATED_MODEL_REPLACEMENTS全部为空值、canonical_model_pair()返回None即没有自动的规范迁移——这是一个明确的不变量陈旧但合法存储的设置永远能解析出可构造的 pair。所有团队默认解析器都遵循同一不变量先取合法已存 pair → 同供应商恢复 →default_model_pair()。三层优先级团队、Profile 与线程生命周期团队设置单一 Store 记录团队设置是 LangGraph Store 中[team_settings]命名空间下、键为default的单一记录agent/dashboard/team_settings.py。读取时get_team_settings将非空存储字段覆盖在硬编码默认值之上且故意 fail-softstore 不可达时退化为默认值而不是让每个 run 同时失败。团队可为 agent 与 reviewer 两个角色分别设置 main/subagent pair可配置字段覆盖了几乎所有模型消费点default_agent_model/default_agent_reasoning_effort/default_agent_subagent_model/default_agent_subagent_reasoning_effortdefault_reviewer_model/default_reviewer_reasoning_effort/default_reviewer_subagent_model/default_reviewer_subagent_reasoning_effortdefault_grouping_modeldiff 分组缺省时继承 reviewer subagent 默认default_chat_modelreview 页 PR 聊天缺省时继承agent默认见get_team_default_model中role chat分支team_settings.pydefault_thread_title_model线程标题默认openai:gpt-5.6-luna effortlowdefault_agent_routing_{fast,balanced,performance}_model自适应路由三档team_settings.py。线程标题有一个专门的降级逻辑_gate_openai_title_modelteam_settings.py在纯 Anthropic 部署上若既无 gateway 路由能力也无桌面 OpenAI OAuth就把 OpenAI 标题模型切换为anthropic:claude-haiku-4-5 effortnone——因为标题是一次性分类任务无需深度思考且避免每次标题生成都因缺OPENAI_API_KEY而失败。Profile与 OAuth 令牌物理隔离[profiles]中的 Profile 记录携带 main pair、可选 subagent pair、默认仓库与分支偏好、PR/CI 偏好ProfileUpdateagent/dashboard/profiles.py。最重要的工程决策是存储命名空间隔离profiles.py[profiles]—— 用户可编辑设置模型、effort、默认仓库[oauth_tokens]—— 加密的 GitHub OAuth access token 与 email。每个 upsert 只触碰自己的命名空间因此 Profile 保存与 OAuth 回调的 token 刷新即使交错执行也不会互相覆盖字段。个人指令则更进一步放在独立的[user_instructions]命名空间见下文避免与 Profile 保存产生写竞争。run 启动时的 Profile 查找是 fail-soft 的load_profile捕获 store 异常返回Noneagent/dashboard/agent_overrides.py而 dashboard 的 Profile 读取则刻意暴露 store 失败让管理员能感知存储问题。线程快照首次运行的解析结果被冻结下面的流程图完整描述了首次运行解析到线程快照的决策链原文出自 models-profiles-instructions.md首次运行解析创建线程快照只有合法的显式运行 pair 才会刻意改变其模型选择。get_agentagent/server.py是这条链路的落地实现从团队 pair 出发仅当线程没有存储的 main model时读取 sender Profile合法的 Profile main pair 在未提供合法 subagent pair 时也同时成为 subagent pair已存储的设置快照随后生效最后合法的configurable.agent_model_id加agent_effort会替换两个 pair 并持久化。线程级设置agent_settings存放在线程 metadata 中实现在 agent/utils/thread_settings.py只接受类型化字段model_id、effort、subagent_model_id、subagent_effort、model_routing_enabled、repo_instructions缓存 5 分钟_CACHE_TTL_SECONDS 300读写均 fail-soft非法的 legacy metadata 会被normalize_thread_settings归一化为空快照。正是这个快照机制让多参与方、长生命周期的线程在任何参与者随时编辑自己 Profile的情况下保持运行期选择稳定同时避免了把某个参与者的偏好错误归因给他人。选择型调用方与图片输入的强制替换对于只需模型 ID 的调用方resolve_agent_model_idagent/dashboard/agent_overrides.py应用优先级per-thread id → 合法 Profile id → 团队默认。Dashboard 创建 run 时则使用完整 pair顺序为团队、Profile、请求agent.server.get_agent中的实现与其一致。被标记为 deprecated 的请求会故意保留团队默认而不是让 Profile 生效。图片输入是一条强制规则如果 dashboard 输入包含图片而解析出的模型是纯文本模型则会被替换为default_vision_model_pair()options.py优先 OpenAI/Anthropic 的图片模型直接以图片内容构造模型时缺少图片模型或纯文本模型会被拒绝并返回 HTTP 422。Fable工作区级 ZDR 门控Fable 是工作区级零数据驻留ZDR门控。三个硬约束贯穿所有入口Fable 选项不能保存为普通默认NON_DEFAULT_MODEL_IDS禁用 Fable 时提交的 Fable 团队默认会被改写为非 Fable 的 Anthropic 回退gate_fable_model配合fable_disabled_fallbackoptions.py快照解析之后gate_fable_model仍会作用于 main、subagent、title 模型dashboard 解析与选项列表同样应用该门控。因此一个过期快照永远不会让被禁用的 Fable 模型出现在广告或构造路径中——无论哪一层选中了它只要门控关闭它都到不了make_model。供应商构造、推理参数、Gateway 与运行时回退provider_model_kwargs在供应商边界翻译 effort解析出的 effort 通过provider_model_kwargsagent/utils/model.py翻译成各供应商的原生参数供应商前缀参数形态细节openai:reasoning: {effort, summary}使用 Responses APIsummary: autonone除外见 model.pyanthropic:thinking: {type: adaptive, display: summarized}effortsummarized保证响应返回可见的推理文本adaptive 默认是omitteddashboard 将无文本可渲染model.pygoogle_genai:Gemini 3 家族thinking_levelnone/minimal→minimalhigh/xhigh/max→highmodel.pyfireworks:model_kwargs.reasoning_effort透传 effort 值baseten:reasoning_effort仅当 effort 为low/high/max时设置make_model六次重试、六百秒超时与缓存make_modelagent/utils/model.py通过 LangChain 的init_chat_model构造模型重试与超时对随附供应商前缀openai/anthropic/baseten/google_genai/fireworks默认max_retries 6、timeout 600秒。注释解释了原因Anthropic SDK 默认重试 2 次一次 529 突发可能超过它而缺失超时会让停滞的供应商连接把 run 挂起最长一小时历史上曾观察到单次调用卡死一小时。让重试把停滞变成重试而不是死 run。OpenAI Responses API默认storeFalse、output_versionresponses/v1、include[reasoning.encrypted_content]加密推理内容见_configure_openai_responses_kwargs。若 gateway 路由未启用且无OPENAI_API_KEY桌面 OAuth 可以提供模型build_desktop_openai_oauth_model。Baseten配置为 OpenAI 兼容供应商未启用 gateway 路由时必须提供BASETEN_API_KEY与服务 URL否则抛出ValueError。缓存模型按(model_id, gateway 请求值, max_tokens, 冻结 kwargs, event-loop id)五元组缓存close_cached_models清空缓存并依次调用aclose/close。LangSmith Gateway三态启用Gateway 启用是三态的agent/utils/gateway.py团队设置gateway_enabled为True/False时一票生效为None时继承LANGSMITH_GATEWAY_ENABLED环境变量未设置时存在专用LANGSMITH_GATEWAY_API_KEY即视为启用见gateway_env_default。当路由可行时gateway_overridesgateway.py会替换直接 base URL 与 API key如https://gateway.smith.langchain.com/openai/v1、/anthropic、/gemini等路径后缀并决定 OpenAI 是否走 Responses API默认走因为带工具调用的 OpenAI 推理模型在 Chat Completions 上拒绝reasoning_effort。不可路由的供应商或缺失 LangSmith key 只会记录日志并保持直连不会让 run 失败——这是刻意的健壮性设计。运行时模型回退与 Gateway 路由正交Gateway 路由与运行时模型回退是两个独立机制。回退由ModelFallbackMiddleware实现设置LLM_FALLBACK_MODEL_ID时使用该值否则 Anthropic 主模型回退到 OpenAI、OpenAI 主模型回退到 Anthropicfallback_model_id_formodel.py。Google、本地与自托管供应商没有自动跨供应商回退——避免把流量静默路由到外部。指令来源与权威层级仓库自定义指令agent_instructions仓库自定义指令是工作区管理员撰写的记录存储于[agent_instructions]命名空间以owner/name为键agent/dashboard/agent_instructions.py。记录字段包括full_name、owner、name、instructions、created_by、created_at、updated_at由AgentInstructionsStore提供create/set_instructions/list_all。新建 hosted 线程时工厂为生效的默认仓库解析指令并将文本保存进线程快照。construct_system_prompt将其渲染为Repository-specific Custom Instructions段落_render_repo_instructions_sectionagent/prompt.py因此它是线程共享的如果查询失败该段落直接缺席而不是中止 run。个人指令user_instructions个人指令是独立的[user_instructions]记录以 GitHub login 为键上限 20,000 字符MAX_USER_INSTRUCTIONS_CHARSagent/dashboard/user_instructions.py。它可以从 dashboard 修改也可以由 agent 通过save_user_instructions工具自行修改因此刻意放在 Profile 之外以避免写竞争。prepare-run 阶段工厂加载触发用户的当前文本并传给construct_sender_contextagent/prompt.py后者生成一条受信任的 sender-context 消息明确声明仅适用于本 turn不得归因于其他线程参与者并附上发送者的 git 身份、工作区管理员标记、草稿 PR 偏好等信息。显式权威层级提示词权威是显式的原文models-profiles-instructions.md仓库的AGENTS.md如存在以与系统提示相同的权威覆盖 prompt 默认仓库自定义指令是强制的但让位于AGENTS.md环境指令让位于仓库指令与AGENTS.md发送者级个人指令让位于仓库指令与AGENTS.md。特别地用户指令不是线程共享指令绝不能覆盖仓库策略。这正是个人偏好按消息重新求值、仓库策略按线程冻结这一分治设计的落点。变更与测试指南当改动注册表、回退逻辑或 Profile 归一化时应优先覆盖以下测试原文列示均已存在于仓库tests/models/test_model_fallback_resolution.py覆盖供应商保持恢复、废弃 id 让位、环境默认、Profile/团队行为、上下文增强与 Fable 处理tests/dashboard/test_dashboard_thread_api.py覆盖团队/Profile/请求优先级与图片校验/回退tests/agent/test_thread_settings.py覆盖类型化快照归一化、缓存与 fail-soft 持久化tests/models/test_agent_subagent_models.py覆盖工厂级继承与显式 subagent 选择。添加新供应商、改动 effort 集合或调整优先级时同步更新上述聚焦用例即可把回归风险锁在这些边界上。延伸阅读运行级决策链总览Agent graph、中间件栈凭据与 OAuth 细节Authentication and security部署环境变量清单Configuration提示词组装与上下文工程Context engineering【免费下载链接】open-sweAn Open-Source Asynchronous Coding Agent项目地址: https://gitcode.com/GitHub_Trending/op/open-swe创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
