第 30 章

模型提供商

为 Deep Agents Code 配置任何兼容 LangChain 的模型提供商

从"只用一家模型"到"灵活切换任意供应商"的关键一步

为什么需要它

你有没有遇到过这些问题：模型 A 不支持工具调用、模型 B 太贵、模型 C 延迟太高？

单模型绑定的困境

只用一个模型，无法按任务选择最合适的供应商
想切换模型？改代码、改环境变量、一套流程走一遍
不同项目需要不同模型？手动管理凭据很混乱
某个模型服务挂了？没有备用方案
新出的模型想试试？不确定兼容性

Deep Agents Code 的解法

支持任何兼容 LangChain 的聊天模型提供商
一条命令切换模型：/model provider:model
凭据统一存在 ~/.deepagents/.env，跨项目复用
模型路由器（OpenRouter、LiteLLM）提供多供应商聚合
安装对应的包就能用——即插即用

问题核心：在真实项目中，你不会只用一个模型——不同任务需要不同模型的"性价比"。Deep Agents Code 让你用统一的方式管理所有模型供应商，切换模型就像切换频道一样简单。

这里"切换频道"只是比喻帮助你理解操作体验。实际上计算机内部做的事情是：更新模型配置字符串（如 anthropic:claude-opus-4-7），重新初始化对应的 LangChain 聊天模型实例，并加载新的 API 端点和参数——与电视频道切换的物理机制完全不同。

快速入门

安装提供商包——每个模型供应商都需要其对应的 LangChain 集成包

Deep Agents Code 基于 Python 构建，模型提供商通过可选附加组件安装。这样设计是为了保持核心包的轻量化——你只需要安装你实际使用的提供商。

# 快速安装指定提供商（通过环境变量指定附加组件）
# OpenAI、Anthropic 和 Gemini 默认已包含，无需额外安装
DEEPAGENTS_CODE_EXTRAS="baseten,groq" curl -LsSf https://langch.in/dcode | bash

# 或者使用 uv 直接安装指定提供商
uv tool install 'deepagents-code[baseten,groq]'

# 已安装后，用 --with 追加额外的提供商包
uv tool install deepagents-code --with langchain-ollama

# 一次性安装所有提供商（按需选择，通常不需要全部）
uv tool install 'deepagents-code[anthropic,baseten,bedrock,cohere,deepseek,\
fireworks,google-genai,groq,huggingface,ibm,litellm,mistralai,nvidia,\
ollama,openai,openrouter,perplexity,vertexai,xai]'

默认已包含

OpenAI — GPT 系列模型
Anthropic — Claude 系列模型
Google GenAI — Gemini 系列模型

按需安装

其他提供商需要通过可选附加组件安装。安装对应的包后即可直接使用，无需额外配置。

追加安装

已安装 Deep Agents Code 后，可以用 --with 参数追加安装额外的提供商包，不影响已有配置。

设置凭据

将 API 密钥存储在 ~/.deepagents/.env 中，跨项目通用

有两种方式设置凭据：永久添加（写入配置文件）和临时导出（仅当前会话）。推荐使用永久方式，这样所有项目都能共享凭据。

OpenAI

# 永久添加——写入配置文件，所有项目共享
mkdir -p ~/.deepagents
echo 'OPENAI_API_KEY=your-api-key' >> ~/.deepagents/.env

# 仅当前会话——关闭终端后失效
export OPENAI_API_KEY="your-api-key"

Anthropic

# 永久添加——写入配置文件，所有项目共享
mkdir -p ~/.deepagents
echo 'ANTHROPIC_API_KEY=your-api-key' >> ~/.deepagents/.env

# 仅当前会话——关闭终端后失效
export ANTHROPIC_API_KEY="your-api-key"

Google

# 永久添加——写入配置文件，所有项目共享
mkdir -p ~/.deepagents
echo 'GOOGLE_API_KEY=your-api-key' >> ~/.deepagents/.env

# 仅当前会话——关闭终端后失效
export GOOGLE_API_KEY="your-api-key"

限定范围

使用 DEEPAGENTS_CODE_ 前缀可以将凭据限定在 Deep Agents Code 范围内，避免与其他工具的凭据冲突。

# 使用 DEEPAGENTS_CODE_ 前缀限定范围，避免与其他工具冲突
echo 'DEEPAGENTS_CODE_ANTHROPIC_API_KEY=xxx' >> ~/.deepagents/.env

其他提供商：Deep Agents Code 可与任何支持工具调用的 LLM 配合使用。完整支持的提供商列表及其所需环境变量请参见提供商参考章节。

配置模型参数：要配置模型参数（温度、推理预算等），请参见模型参数章节。

安全提示：不要将 ~/.deepagents/.env 文件提交到版本控制。建议将此文件加入 .gitignore。API 密钥是敏感信息，泄露可能导致未经授权的调用和费用。

提供商一览

Deep Agents Code 支持广泛的模型提供商——安装对应的包即可使用

Deep Agents Code 支持任何兼容 LangChain 的聊天模型提供商。几乎所有支持工具调用的 LLM 都可以使用。任何提供兼容 OpenAI 或兼容 Anthropic API 的服务也可以直接使用。

提供商	附加组件	环境变量
OpenAI	默认包含	`OPENAI_API_KEY`
Anthropic	默认包含	`ANTHROPIC_API_KEY`
Google GenAI	默认包含	`GOOGLE_API_KEY`
Ollama	`[ollama]`	本地运行，无需密钥
Groq	`[groq]`	`GROQ_API_KEY`
DeepSeek	`[deepseek]`	`DEEPSEEK_API_KEY`
Mistral	`[mistralai]`	`MISTRAL_API_KEY`
AWS Bedrock	`[bedrock]`	AWS 凭据
Vertex AI	`[vertexai]`	`GOOGLE_CLOUD_PROJECT`

兼容 API：如果你的模型提供商提供兼容 OpenAI 或兼容 Anthropic 的 API，你可以直接使用，无需安装额外的包。只需配置自定义 Base URL 即可。

路由与代理

模型路由器通过单一端点访问来自多个提供商的模型

如果你不想为每个提供商单独配置凭据，可以使用模型路由器——一个端点聚合所有模型，统一计费、统一管理。

OpenRouter

通过单一 API 访问来自 OpenAI、Anthropic、Google、Meta 等多个提供商的模型。

# 安装 OpenRouter 集成
uv tool install 'deepagents-code[openrouter]'

内置提供商安装包后即可直接使用

LiteLLM

将 100+ 模型提供商统一为 OpenAI 格式的代理，支持自定义端点。

# 安装 LiteLLM 集成
uv tool install 'deepagents-code[litellm]'

内置提供商安装包后即可直接使用

路由器的优势

单一凭据 — 只需管理一个 API 密钥
统一计费 — 所有模型费用合并
快速试新 — 即时访问新发布的模型

适用场景

需要在多个模型之间频繁切换
不想为每个提供商单独注册和管理凭据
想快速评估不同模型在你的任务上的表现

切换模型

三种方式切换模型——交互式选择器、直接指定、启动参数

在 Deep Agents Code 中切换模型非常灵活，根据你的使用场景选择最合适的方式。

方式一：交互式选择器

使用 /model 命令打开交互式模型选择器。它会显示所有已安装提供商的可用模型。

# 打开模型选择器
/model

# 选择器会显示：
# - 每个提供商下所有符合条件的模型
# - 凭据状态（勾选/警告/问号）
# - 模型能力信息

方式二：直接指定

直接传入模型名称，跳过选择器。支持提供商支持的任何模型。

# 直接切换到指定模型
/model gpt-5.5

# 指定提供商和模型
/model anthropic:claude-opus-4-7
/model openai:gpt-5.5

方式三：启动参数

在启动 Deep Agents Code 时通过 --model 参数指定模型。

# 启动时指定模型
dcode --model openai:gpt-5.5

# 启动时指定模型和参数
dcode --model openai:gpt-5.5 \
  --model-params '{"temperature": 0.7}'

提示：并非所有模型都会出现在交互式选择器中。如果你的模型未显示，可以直接传入模型名称（例如 /model gpt-5.5）。

解析顺序

Deep Agents Code 启动时按以下优先级解析要使用的模型

了解模型解析顺序，可以帮助你排查"为什么用的不是我想要的模型"这类问题。

1. --model 标志

最高优先级，始终覆盖其他设置

2. default 配置

config.toml 中的 [models].default

3. recent 配置

config.toml 中的 [models].recent

4. 环境检测

自动检测可用的 API 密钥

环境自动检测顺序

当没有任何配置时，Deep Agents Code 按以下顺序检查凭据：

OPENAI_API_KEY
ANTHROPIC_API_KEY
GOOGLE_API_KEY
GOOGLE_CLOUD_PROJECT（Vertex AI）

注意事项

环境自动检测仅检查这四个凭据
其他提供商（如 Groq）需通过 --model、/model 或配置文件来使用
[models].recent 由系统自动写入，不会覆盖 [models].default

核心原则：--model > 配置文件 default > 配置文件 recent > 环境自动检测。如果你设置了默认模型但临时想用另一个，用 --model 标志即可覆盖。

模型选择器

交互式 /model 选择器动态构建模型列表——不是硬编码的固定列表

一个模型要出现在选择器中，需要同时满足以下所有条件：

条件 1：已安装提供商包

每个提供商必须与 deepagents-code 一起安装。如果缺少某个包，该提供商的整个部分都不会出现在选择器中。

条件 2：启用工具调用

模型的配置文件中必须设置 tool_calling: true。这是模型未出现在列表中最常见的原因。对于不捆绑配置文件的提供商，你可以在 config.toml 中定义：

[models.providers.ollama.profile."qwen3:4b"]
tool_calling = true        # 声明该模型支持工具调用（必须为 true 才会出现在选择器中）
max_input_tokens = 32768   # 最大输入 token 数，影响上下文窗口
max_output_tokens = 8192   # 最大输出 token 数

条件 3：接受文本

模型必须接受文本输入并生成文本输出。配置文件中将 text_inputs 或 text_outputs 设为 false 的模型会被排除。

故障排除

症状	可能原因	解决方法
整个提供商缺失	未安装提供商包	`uv tool install deepagents-code --with langchain-groq`
提供商显示但特定模型缺失	`tool_calling: false` 或没有配置文件	在 `config.toml` 的 `[models.providers.<name>].models` 中添加
提供商显示警告"缺少凭据"	未设置 API 密钥	设置对应的环境变量
提供商显示"凭据未知"	提供商使用非标准认证	凭据可能仍然有效，尝试切换到该模型

凭据状态提示：凭据状态不会影响模型是否列出。选择器会显示所有符合条件的模型，并在每个提供商标题旁显示凭据指示器：已确认凭据显示勾选标记，缺少凭据显示警告，凭据状态未知显示问号。你仍然可以选择缺少凭据的模型——提供商将在请求时报告认证错误。

绕过过滤器：在 config.toml 的 [models.providers.<name>].models 中定义的模型会绕过配置文件过滤器，总是会出现在选择器中。这是添加缺失模型的推荐方式。

默认模型

设置持久化默认模型——所有未来的 CLI 启动都使用它

你可以通过多种方式设置默认模型。设置后，每次启动 Deep Agents Code 都会自动使用该模型，无需手动指定。

设置默认模型

选择器：打开 /model，导航到目标模型，按 Ctrl+S 固定
命令：/model --default provider:model
配置文件：在 ~/.deepagents/config.toml 中设置 [models].default
命令行：dcode --default-model anthropic:claude-opus-4-7

查看与清除

# 查看当前设置的默认模型
dcode --default-model

# 清除默认模型设置，回退到环境自动检测
dcode --clear-default-model

也可以通过以下方式清除：

命令：/model --default --clear
选择器：在当前固定的默认模型上按 Ctrl+S

注意：如果没有设置默认模型，Deep Agents Code 将默认使用最近使用的模型（[models].recent）。如果也没有最近使用的模型，则回退到环境自动检测。

模型参数

三种配置位置传递额外的构造函数参数——采样控制、推理预算、超时等

你可以将底层聊天模型类接受的任何参数传递给模型——温度、推理力度、上下文窗口大小、请求超时等。有三个设置位置，按优先级从高到低排列：

优先级 1：启动参数

通过 --model-params 一次性设置，JSON 格式，仅对当前会话有效。

# OpenAI 推理力度——high 表示更多推理步骤，适合复杂任务
dcode --model openai:gpt-5.5 \
  --model-params '{"reasoning": {"effort": "high"}}'

# Anthropic 扩展思考——启用思考模式并分配 token 预算
dcode --model anthropic:claude-opus-4-7 \
  --model-params '{"thinking": {"type": "enabled", \
  "budget_tokens": 10000}, "max_tokens": 16000}'

优先级 2：会话中途

通过 /model --model-params 在运行中切换参数，无需重启。

# 切换模型并同时设置参数
/model --model-params '{"temperature": 0.7}' \
  anthropic:claude-opus-4-7

# 打开选择器，参数应用到所选模型
/model --model-params '{"num_ctx": 16384}'

优先级 3：配置文件

在 config.toml 中持久化设置，每次启动时生效。

[models.providers.anthropic.params]
# 启用扩展思考并设置 10000 token 的思考预算
thinking = { type = "enabled", budget_tokens = 10000 }
# 最大输出 token 数（需大于 budget_tokens，因为思考 + 回答共享此限制）
max_tokens = 16000

灵活且强大：底层聊天模型构造函数接受的任何关键字参数都是有效的。未知的关键字参数会被转发到上游 API 请求中，因此新发布的参数无需更新 CLI 即可使用。

参数配置

config.toml 中的提供商级别默认值——支持按模型覆盖

[models.providers.anthropic.params]
# 启用扩展思考，budget_tokens 控制模型"内心独白"的 token 上限
thinking = { type = "enabled", budget_tokens = 10000 }
# max_tokens 必须大于 budget_tokens，因为思考和输出共享此限制
max_tokens = 16000

[models.providers.openai.params]
# 推理力度：high（更深入）/ medium / low（更快）
reasoning = { effort = "high", summary = "auto" }
# 使用 OpenAI Responses API 格式
output_version = "responses/v1"

[models.providers.ollama.params]
# Ollama Provider 级别的默认参数
num_ctx = 16384      # 上下文窗口大小
temperature = 0      # 确定性输出，适合代码生成

# 按模型覆盖——优先级高于 Provider 级别的设置
[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5    # qwen3:4b 单独使用更高的 temperature，增加多样性

配置优先级

CLI 标志（--model-params）— 最高优先级，仅当前会话
按模型子表（params."model_name"）— 覆盖提供商级别
提供商级别（params）— 每次启动生效

CLI 标志覆盖配置文件中的 params，且仅对当前会话有效（会话中途的更改不会被持久化）。config.toml 中的按模型子表会覆盖提供商级别的设置（浅合并——完整语义请参见模型构造函数参数）。--model-params 不能与 --default 同时使用。

支持哪些参数？

所有底层聊天模型构造函数接受的参数
如 temperature、max_tokens、reasoning、thinking 等
未知参数会被转发到上游 API
新发布的参数无需更新 CLI 即可使用

重要：不要在 params 中放置凭据（如 api_key）。请使用 api_key_env 指向一个环境变量。将密钥放在配置文件中是不安全的做法。

高级配置

提供商参数、配置文件覆盖、自定义 Base URL、兼容 API 和生命周期钩子

有关提供商参数、配置文件覆盖、自定义 Base URL、兼容 API、任意提供商和生命周期钩子的详细配置，请参见配置。

提供商参数

每个提供商支持的特定参数配置，包括自定义 Base URL、API 版本等。

配置文件覆盖

覆盖模型的配置文件字段（如 max_input_tokens、tool_calling、能力标志等）。

兼容 API

任何提供兼容 OpenAI 或兼容 Anthropic API 的服务都可以直接使用，无需安装额外的包。

生命周期钩子

在 Deep Agents Code 的生命周期事件中执行自定义脚本或操作。

下一步：这些高级配置在下一章中有详细讲解。如果你需要定制提供商行为或集成自定义 API，请继续深入学习。

本章回顾

到这里，你已经掌握了 Deep Agents Code 模型提供商的完整配置

你学到了什么

Deep Agents Code 支持任何兼容 LangChain 的聊天模型提供商
安装提供商包 + 设置凭据 = 两步完成配置
三种切换模型方式：选择器、直接指定、启动参数
模型解析的四级优先级：标志 > 默认 > 最近 > 环境
模型路由器（OpenRouter、LiteLLM）提供多供应商聚合
模型参数有三个配置位置：启动、会话、配置文件
故障排除：模型不显示时检查包安装和工具调用配置

后续章节预告

配置详解 — 提供商参数、配置文件覆盖、自定义 Base URL
MCP 工具 — 连接外部工具和服务器
数据位置 — 理解文件和数据的存储位置

核心结论：Deep Agents Code 的模型配置设计遵循"按需安装、统一管理、灵活切换"的原则。你只需要安装你用到的提供商，凭据统一存储，模型随时切换。这种设计让你在多模型环境中保持高效和安全。