GPT-5.6 Sol 如何在 OpenAI Agents SDK 中配置为默认模型？

要把 GPT-5.6 Sol 配置成 OpenAI Agents SDK 的默认模型，最直接的做法是在启动 Python 进程前设置 OPENAI_DEFAULT_MODEL=gpt-5.6-sol。之后，凡是没有在 Agent 上单独指定模型、也没有被本次运行配置覆盖的 Agent，都会通过默认 OpenAI provider 使用这个模型。对于只想影响某一次 Runner 调用的场景，应改用 RunConfig(model="gpt-5.6-sol")；如果只有某个 Agent 需要使用它，则直接在该 Agent 上设置 model="gpt-5.6-sol"。这三种入口对应进程级、运行级和 Agent 级三个不同作用域。

先理解 SDK 的默认模型从哪里来

Agents SDK 允许把模型名称写成字符串，由默认 OpenAI provider 将其解析成可调用的模型实现。使用 OpenAI 模型时，推荐保留默认的 Responses API 路径。若代码没有为 Agent 指定模型，也没有提供其他覆盖配置，SDK 会采用自身内置的默认模型；因此，“把 GPT-5.6 Sol 设为默认模型”并不是修改 SDK 源码，而是在模型解析发生前提供一个更高优先级的默认值。

配置时应使用准确的模型标识 gpt-5.6-sol。模型的显示名称可以写成“GPT-5.6 Sol”，但传给 SDK 的字符串不能混入空格、大小写变体或自行拼出的版本后缀。API 密钥仍由 OPENAI_API_KEY 提供，模型配置不会替代鉴权配置。

方法一：用环境变量设置进程级默认模型

如果一个应用中的大多数 Agent 都应该使用 GPT-5.6 Sol，环境变量是最省事的入口。在启动程序的同一个终端中执行：

export OPENAI_API_KEY="your_api_key"
export OPENAI_DEFAULT_MODEL="gpt-5.6-sol"
python3 app.py

应用代码不必在每个 Agent 上重复模型名称：

import asyncio
from agents import Agent, Runner

assistant = Agent(
    name="Assistant",
    instructions="用简洁、准确的中文回答。",
)

async def main():
    result = await Runner.run(assistant, "解释什么是幂等性")
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

这种方式适合容器、服务进程和统一部署配置。环境变量必须对实际启动 Python 的进程可见。在一个终端里执行 export，不会自动影响另一个已经打开的终端，也不会改变已经运行的服务。修改后应重启目标进程，避免误以为旧进程会动态读取新值。

部署系统中可以把 OPENAI_DEFAULT_MODEL 与密钥分开管理：模型名属于普通配置，密钥属于敏感信息。不要为了设置默认模型而把 API 密钥写入源码、镜像或版本库。

方法二：用 RunConfig 设置单次运行的默认模型

当同一进程需要按任务选择模型，或者希望在测试中明确控制某次运行，应使用 RunConfig。它只为本次运行提供默认模型，不要求修改整个进程的环境：

import asyncio
from agents import Agent, RunConfig, Runner

assistant = Agent(
    name="Assistant",
    instructions="先分析约束，再给出可执行结论。",
)

async def main():
    result = await Runner.run(
        assistant,
        "设计一个支持重试的任务处理流程",
        run_config=RunConfig(model="gpt-5.6-sol"),
    )
    print(result.final_output)

if __name__ == "__main__":
    asyncio.run(main())

这里的“运行级默认”很重要：它用于没有自行声明模型的 Agent。若工作流中某个 Agent 已经显式指定了模型，就应把该显式设置视为有意的局部选择，而不是期待运行级配置强行替换它。实际项目中，最好把覆盖关系写进测试，尤其是包含 handoff、Agent-as-tool 或多个专业 Agent 的工作流。

方法三：只为某个 Agent 显式指定

如果只有少数高难度任务需要 GPT-5.6 Sol，直接在 Agent 上配置更清楚：

from agents import Agent

research_agent = Agent(
    name="Research Agent",
    instructions="核对证据，区分事实与推断。",
    model="gpt-5.6-sol",
)

这种写法严格来说不是“全局默认”，但它最容易审计，也能避免所有 Agent 都使用同一能力和成本档位。一个常见架构是让普通路由或格式化任务沿用较轻量的默认模型，只给复杂推理 Agent 显式配置 GPT-5.6 Sol。

为 GPT-5.6 Sol 配置推理参数

选定模型与设置模型参数是两件事。模型名称决定调用哪个模型，ModelSettings 决定该调用如何运行。Agents SDK 会为 GPT-5 系列提供适合常见场景的默认设置；需要明确控制推理强度或输出详细程度时，再传入自己的配置：

from agents import Agent, ModelSettings
from openai.types.shared import Reasoning

planner = Agent(
    name="Planner",
    instructions="分析需求并生成实施计划。",
    model="gpt-5.6-sol",
    model_settings=ModelSettings(
        reasoning=Reasoning(effort="high"),
        verbosity="low",
    ),
)

如果已经设置了 OPENAI_DEFAULT_MODEL=gpt-5.6-sol，Agent 可以省略 model，只保留 model_settings。不过在多人维护的代码库里，显式模型名有时更便于理解该 Agent 的能力和成本意图。低延迟任务可考虑 reasoning.effort="none"；复杂任务再提高 effort。不要机械地给所有调用设成最高推理强度，因为响应时间和资源消耗也会随之变化。

GPT-5.6 的部分高级推理控制只适用于 Responses API 路径。若项目为了兼容第三方 provider 主动切换到 Chat Completions，应先核对目标路径支持哪些字段；不要假设两个 API 形态会接受完全相同的模型设置。对纯 OpenAI 应用，保持 SDK 默认的 Responses 路径通常最直接。

推荐的配置组织方式

生产项目可以让默认模型由环境决定，同时允许少量 Agent 局部覆盖。下面的结构把部署选择与业务代码分离：

# .env.example，只展示变量名和非敏感示例
OPENAI_DEFAULT_MODEL=gpt-5.6-sol

# 实际运行环境还需安全注入 OPENAI_API_KEY

from agents import Agent

general_agent = Agent(
    name="General",
    instructions="处理常规请求。",
)

specialist_agent = Agent(
    name="Specialist",
    instructions="处理需要深入分析的请求。",
    model="gpt-5.6-sol",
)

若整个系统都固定使用 GPT-5.6 Sol，第二个 Agent 的显式配置可以删除；若系统采用混合模型，则应保留。关键是让默认策略只有一个清晰入口，避免环境变量、运行配置和 Agent 配置在不同文件中无意叠加。

如何验证配置确实生效

验证不应只看程序是否输出文本，因为错误的模型同样可能正常回答。首先确认启动进程能读取环境变量：

python3 -c 'import os; print(os.getenv("OPENAI_DEFAULT_MODEL"))'

输出应为 gpt-5.6-sol。随后用一个未设置 model 的最小 Agent 发起调用，并开启应用已有的请求日志或 tracing，检查实际请求记录中的模型。日志中不要打印 API 密钥、Authorization 请求头或完整敏感输入。

还应增加两个小型回归测试：一个确认无显式模型的 Agent 使用应用预期的默认配置，另一个确认显式模型的 Agent 不会被全局默认意外替换。这样在升级 SDK、调整部署变量或重构 Runner 调用时，模型路由变化能尽早暴露。

常见问题与排查顺序

设置后仍然没有使用 GPT-5.6 Sol

先检查变量是否设置在正确的进程环境中，再搜索代码里是否存在 RunConfig(model=...) 或 Agent 自身的 model=...。容器环境还要确认变量是否真正注入运行容器，而不只是写在宿主机的 shell 配置里。修改配置后应重启服务。

收到鉴权错误

OPENAI_DEFAULT_MODEL 只负责模型选择。鉴权仍依赖有效的 OPENAI_API_KEY。应分别检查两个变量，不要把模型不可用、账户权限和密钥错误混为一类。错误信息不明确时，保留状态码和请求 ID用于内部排查，但不要公开密钥。

高级设置被忽略或报错

确认代码使用的是 OpenAI Responses 模型路径，并核对当前 SDK 对相应 ModelSettings 字段的支持。若项目切换了默认 API、使用自定义 provider 或兼容接口，功能集合可能不同。先用只包含模型名的最小示例验证连通性，再逐项加入推理、工具和传输设置，能更快定位是哪一项造成不兼容。

多 Agent 工作流中的模型不一致

逐个检查根 Agent、handoff 目标和作为工具调用的 Agent 是否显式设置了模型。全局默认的意义是为“未指定模型”的对象补上选择，而不是抹掉所有局部配置。对于成本或能力敏感的工作流，建议在代码审查中把每个显式覆盖视为架构决策。

选择哪一种方式

希望一个服务内所有未指定模型的 Agent 默认使用 GPT-5.6 Sol，就设置 OPENAI_DEFAULT_MODEL；希望只控制一次 Runner 执行，就使用 RunConfig；希望固定某个 Agent 的模型，就设置 Agent 的 model。三种方式可以共存，但应保持覆盖关系明确。配置完成后，通过进程环境、请求日志或 tracing 验证实际模型，而不是仅凭回答风格判断。这样既能稳定地把 GPT-5.6 Sol 作为默认模型，也能在多 Agent 系统中保留必要的局部模型选择。