自定义模型提供商

Deep Agents CLI 支持任何兼容 LangChain 的聊天模型提供商，这使得几乎所有支持工具调用的 LLM 都能被使用。任何提供 OpenAI 兼容或 Anthropic 兼容 API 的服务也可以开箱即用 —— 请参阅兼容 API。

快速开始

CLI 自动集成了以下模型提供商 —— 除了安装相关的提供商包之外，无需额外配置。

安装提供商包 每个模型提供商都需要安装其对应的 LangChain 集成包。这些包在安装 CLI 时作为可选的额外组件提供：

# 安装单个提供商
uv tool install 'deepagents-cli[anthropic]'

# 同时安装多个提供商
uv tool install 'deepagents-cli[anthropic,openai,groq]'

# 日后添加额外的包
uv tool upgrade deepagents-cli --with langchain-ollama

# 所有提供商
uv tool install 'deepagents-cli[anthropic,bedrock,cohere,deepseek,fireworks,google-genai,groq,huggingface,ibm,mistralai,nvidia,ollama,openai,openrouter,perplexity,vertexai,xai]'

设置凭据 大多数提供商需要 API 密钥。设置下表中列出的相应环境变量。某些提供商使用其他凭据（例如，Vertex AI 使用 GOOGLE_CLOUD_PROJECT 加上 ADC）。有关详细信息，请参阅每个集成包的文档。

提供商参考

使用此处未列出的提供商？请参阅任意提供商 —— 任何兼容 LangChain 的提供商只要稍作设置即可在 CLI 中使用。

提供商	包	凭据环境变量	模型配置文件
OpenAI	`langchain-openai`	`OPENAI_API_KEY`	✅
Anthropic	`langchain-anthropic`	`ANTHROPIC_API_KEY`	✅
Google Gemini API	`langchain-google-genai`	`GOOGLE_API_KEY`	✅
Google Vertex AI	`langchain-google-vertexai`	`GOOGLE_CLOUD_PROJECT`	✅
AWS Bedrock	`langchain-aws`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	✅
AWS Bedrock Converse	`langchain-aws`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`	✅
Ollama	`langchain-ollama`	可选	❌
Groq	`langchain-groq`	`GROQ_API_KEY`	✅
Cohere	`langchain-cohere`	`COHERE_API_KEY`	❌
Fireworks	`langchain-fireworks`	`FIREWORKS_API_KEY`	✅
DeepSeek	`langchain-deepseek`	`DEEPSEEK_API_KEY`	✅
xAI	`langchain-xai`	`XAI_API_KEY`	✅
Perplexity	`langchain-perplexity`	`PPLX_API_KEY`	✅

模型配置文件 是随提供商包一起发布的一组元数据（模型名称、默认参数、功能等），主要由 models.dev 项目提供支持。包含模型配置文件的提供商会自动在交互式 /model 切换器中列出其模型。没有模型配置文件的提供商需要您直接指定模型名称。

切换模型

要在 CLI 中切换模型，可以通过以下任一方式：

使用交互式模型切换器 通过 /model 命令。这将显示从每个 LangChain 提供商包获取的已知模型配置文件的硬编码列表。
请注意，这些配置文件并非可用模型的详尽列表。如果您想要使用的模型未显示，请改用选项 2（这对于尚未添加到配置文件的新发布模型很有用）。
直接指定模型名称 作为参数，例如 /model openai:gpt-4o。您可以使用所选提供商支持的任何模型，无论它是否出现在选项 1 的列表中。模型名称将传递给 API 请求。
在启动时指定模型 通过 --model，例如
```
deepagents --model openai:gpt-4o
```

设置默认模型

您可以设置一个持久的默认模型，该模型将用于所有未来的 CLI 启动：

通过模型选择器： 打开 /model，导航到所需的模型，然后按 Ctrl+S 将其固定为默认值。在当前默认值上再次按 Ctrl+S 可清除它。
通过命令： /model --default provider:model（例如，/model --default anthropic:claude-opus-4-6）
通过配置文件： 在 ~/.deepagents/config.toml 中设置 [models].default（请参阅配置文件）。

从 Shell：

deepagents --default-model anthropic:claude-opus-4-6

要查看当前默认值：

deepagents --default-model

要清除默认值：

从 Shell：
```
deepagents --clear-default-model
```
通过命令： /model --default --clear
通过模型选择器： 在当前固定的默认模型上按 Ctrl+S。

如果没有默认值，CLI 将默认为最近使用的模型。

模型解析顺序

当 CLI 启动时，它按以下顺序解析要使用的模型：

--model 标志 如果提供，总是优先。
[models].default 在 ~/.deepagents/config.toml 中 —— 用户的有意长期偏好。
[models].recent 在 ~/.deepagents/config.toml 中 —— 通过 /model 切换到的最后一个模型。自动写入；从不覆盖 [models].default。
环境自动检测 —— 回退到第一个可用的启动凭据，按顺序检查：OPENAI_API_KEY、ANTHROPIC_API_KEY、GOOGLE_API_KEY、GOOGLE_CLOUD_PROJECT (Vertex AI)。

此启动回退特意仅检查这四个凭据。其他受支持的提供商（例如 Groq）仍可通过 --model、/model 和保存的默认值（[models].default / [models].recent）使用。

配置文件

Deep Agents CLI 提供了通过 ~/.deepagents/config.toml 扩展和修改单个模型及提供商配置的功能。每个提供商都是 [models.providers] 命名空间下的一个 TOML 表：

[models.providers.<name>]
models = ["gpt-4o"]
api_key_env = "OPENAI_API_KEY"
base_url = "https://api.openai.com/v1"
class_path = "my_package.models:MyChatModel"

[models.providers.<name>.params]
temperature = 0
max_tokens = 4096

[models.providers.<name>.params."gpt-4o"]
temperature = 0.7

键：

models

string[]

要为此提供商在交互式 /model 切换器中显示的模型名称列表。对于已经附带模型配置文件的提供商，您在此处添加的任何名称都会与捆绑的名称一起显示 —— 这对于尚未添加到包中的新发布模型很有用。对于任意提供商，此列表是切换器中模型的唯一来源。此键是可选的。无论模型名称是否出现在切换器中，您始终可以直接将其传递给 /model 或 --model；提供商会在请求时验证该名称。

api_key_env

string

可选地覆盖用于检查凭据的环境变量名称。

base_url

string

如果支持，可选地覆盖提供商使用的基本 URL。有关更多信息，请参阅您的提供商包的参考文档。

params

object

转发给模型构造函数的额外关键字参数。扁平键（例如，temperature = 0）适用于来自此提供商的每个模型。以模型为键的子表（例如，[params."gpt-4o"]）仅覆盖该模型的单个值；合并是浅层的（发生冲突时模型胜出）。

profile

object

（高级）覆盖模型的运行时配置文件中的字段（例如，max_input_tokens）。扁平键适用于来自此提供商的每个模型。以模型为键的子表（例如，[profile."claude-sonnet-4-5"]）仅覆盖该模型的单个值；合并是浅层的（发生冲突时模型胜出）。这些覆盖在模型创建后应用，因此它们会对上下文限制显示、自动摘要以及任何读取配置文件的功能生效。

class_path

string

用于任意模型提供商。module.path:ClassName 格式的可选全限定 Python 类。设置后，CLI 会直接为提供商 <name> 导入并实例化此类。该类必须是 BaseChatModel 的子类。

您可以在 ~/.deepagents/config.toml 中设置默认模型 —— 可以通过直接编辑文件、使用 /model --default 或在交互式模型切换器中选择默认值来实现。

[models]
default = "ollama:qwen3:4b"        # 您的有意长期偏好
recent = "anthropic:claude-sonnet-4-5"  # 上次 /model 切换（自动写入）

[models].default 始终优先于 [models].recent。/model 命令仅写入 [models].recent，因此您配置的默认值绝不会被会话中的切换覆盖。要删除默认值，请使用 /model --default --clear 或从配置文件中删除 default 键。

示例

模型构造函数参数

任何提供商都可以使用 params 表向模型构造函数传递额外参数：

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

每个模型的覆盖

如果特定模型需要不同的参数，请在 params 下添加一个以模型为键的子表以覆盖单个值，而无需复制整个提供商配置：

[models.providers.ollama]
models = ["qwen3:4b", "llama3"]

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5
num_ctx = 4000

使用此配置：

ollama:qwen3:4b 获得 {temperature: 0.5, num_ctx: 4000} —— 模型覆盖胜出。
ollama:llama3 获得 {temperature: 0, num_ctx: 8192} —— 无覆盖，仅提供商级别的参数。

合并是浅层的：模型子表中存在的任何键都会替换提供商级别参数中的相同键，而仅在提供商级别存在的键将被保留。

配置文件覆盖

(高级) 覆盖模型的运行时配置文件中的字段以更改 CLI 解释模型功能的方式。最常见的用例是降低 max_input_tokens 以更早触发自动摘要 —— 这对于测试或限制上下文使用很有用：

# 适用于此提供商的所有模型
[models.providers.anthropic.profile]
max_input_tokens = 4096

每个模型的子表的工作方式与 params 相同 —— 模型级别的值在冲突时胜出：

[models.providers.anthropic.profile]
max_input_tokens = 4096

# 此模型获得更高的限制
[models.providers.anthropic.profile."claude-sonnet-4-5"]
max_input_tokens = 8192

配置文件覆盖会在创建后合并到模型的配置文件中。任何读取配置文件的功能 —— 状态栏中的上下文限制显示、自动摘要阈值、功能检查 —— 都将看到覆盖后的值。

使用 `--model-params` 的 CLI 覆盖

要进行一次性调整而无需编辑配置文件，请通过 --model-params 传递 JSON 对象：

deepagents --model ollama:llama3 --model-params '{"temperature": 0.9, "num_ctx": 16384}'

# 在非交互模式下
deepagents -n "Summarize this repo" --model ollama:llama3 --model-params '{"temperature": 0}'

这些具有最高优先级，覆盖配置文件参数中的值。

使用 `--profile-override` 的 CLI 配置文件覆盖

(高级) 要在运行时覆盖模型配置文件字段而无需编辑配置文件，请通过 --profile-override 传递 JSON 对象：

deepagents --profile-override '{"max_input_tokens": 4096}'

# 与 --model 结合使用
deepagents --model anthropic:claude-sonnet-4-5 --profile-override '{"max_input_tokens": 4096}'

# 在非交互模式下
deepagents -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'

这些被合并在配置文件覆盖之上（CLI 胜出）。优先级链为：模型默认值 < config.toml 配置文件 < CLI --profile-override。

指定自定义 `base_url`

某些提供商包接受 base_url 以覆盖默认端点。例如，langchain-ollama 通过底层 ollama 客户端默认为 http://localhost:11434。要将其指向其他位置，请在配置中设置 base_url：

[models.providers.ollama]
base_url = "http://your-host-here:port"

有关兼容性信息和其他注意事项，请参阅您提供商的参考文档。

模型路由器和代理

模型路由器如 OpenRouter 和 LiteLLM 提供通过单个端点访问来自多个提供商的模型的服务。使用这些服务的专用集成包：

路由器	包
OpenRouter	`langchain-openrouter`

OpenRouter 是内置提供商 —— 安装该包并直接使用它：

uv tool install 'deepagents-cli[openrouter]'

兼容 API

对于公开与 OpenAI 或 Anthropic 线路兼容 API 的提供商，您可以通过将 base_url 指向提供商的端点来使用现有的 langchain-openai 或 langchain-anthropic 包：

[models.providers.openai]
base_url = "https://api.example.com/v1"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-model"]

[models.providers.anthropic]
base_url = "https://api.example.com"
api_key_env = "EXAMPLE_API_KEY"
models = ["my-model"]

提供商在官方规范之上添加的任何功能都不会被捕获。如果提供商提供专用的 LangChain 集成包，请优先使用它。

将模型添加到交互式切换器

某些提供商（例如 langchain-ollama）—— 不捆绑模型配置文件数据（完整列表请参阅提供商参考）。在这种情况下，交互式 /model 切换器将不会列出该提供商的模型。您可以通过在配置文件的提供商中定义 models 列表来填补这一空白：

[models.providers.ollama]
models = ["llama3", "mistral", "codellama"]

/model 切换器现在将包含一个列出这些模型的 Ollama 部分。这完全是可选的。您始终可以通过直接指定全名来切换到任何模型：

/model ollama:llama3

任意提供商

您可以使用 class_path 使用任何 LangChain BaseChatModel 子类。CLI 将直接导入并实例化它：

[models.providers.my_custom]
class_path = "my_package.models:MyChatModel"
api_key_env = "MY_API_KEY"
base_url = "https://my-endpoint.example.com"

[models.providers.my_custom.params]
temperature = 0
max_tokens = 4096

该包必须安装在与 deepagents-cli 相同的 Python 环境中：

# 如果 deepagents-cli 是使用 uv tool 安装的：
uv tool upgrade deepagents-cli --with my_package

当您切换到 my_custom:my-model-v1（通过 /model 或 --model）时，模型名称（my-model-v1）将作为 model kwarg 传递：

MyChatModel(model="my-model-v1", base_url="...", api_key="...", temperature=0, max_tokens=4096)

class_path 从您的配置文件执行任意 Python 代码。这与 pyproject.toml 构建脚本具有相同的信任模型 —— 您控制自己的机器。

您的提供商包可以选择在 <package>.data._profiles 中的 _PROFILES 字典中提供模型配置文件，以代替在 models 键下定义它们。有关更多信息，请参阅 LangChain 模型配置文件。

在 GitHub 上编辑此页面或提交 issue.

将这些文档连接到 Claude, VSCode, 以及更多通过 MCP 获取实时答案。

Get started

Core capabilities

Streaming

Deep Agents CLI

快速开始

提供商参考

切换模型

设置默认模型

模型解析顺序

配置文件

示例

模型构造函数参数

每个模型的覆盖

配置文件覆盖

使用 `--model-params` 的 CLI 覆盖

使用 `--profile-override` 的 CLI 配置文件覆盖

指定自定义 `base_url`

模型路由器和代理

兼容 API

将模型添加到交互式切换器

任意提供商

Get started

Core capabilities

Streaming

Deep Agents CLI

​快速开始

​提供商参考

​切换模型

​设置默认模型

​模型解析顺序

​配置文件

​示例

​模型构造函数参数

​每个模型的覆盖

​配置文件覆盖

​使用 --model-params 的 CLI 覆盖

​使用 --profile-override 的 CLI 配置文件覆盖

​指定自定义 base_url

​模型路由器和代理

​兼容 API

​将模型添加到交互式切换器

​任意提供商

快速开始

提供商参考

切换模型

设置默认模型

模型解析顺序

配置文件

示例

模型构造函数参数

每个模型的覆盖

配置文件覆盖

使用 `--model-params` 的 CLI 覆盖

使用 `--profile-override` 的 CLI 配置文件覆盖

指定自定义 `base_url`

模型路由器和代理

兼容 API

将模型添加到交互式切换器

任意提供商