自定义模型提供商

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

快速开始

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

安装提供商包 每个模型提供商需要安装相应的 LangChain 集成包。安装 CLI 时，这些包可作为可选扩展项：

# Install with one provider
uv tool install 'deepagents-cli[anthropic]'

# Install with multiple providers at once
uv tool install 'deepagents-cli[anthropic,openai,groq]'

# Add additional packages at a later date
uv tool upgrade deepagents-cli --with langchain-ollama

# All providers
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`	✅
Azure OpenAI	`langchain-openai`	`AZURE_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`	✅
Hugging Face	`langchain-huggingface`	`HUGGINGFACEHUB_API_TOKEN`	✅
Ollama	`langchain-ollama`	可选	❌
Groq	`langchain-groq`	`GROQ_API_KEY`	✅
Cohere	`langchain-cohere`	`COHERE_API_KEY`	❌
Fireworks	`langchain-fireworks`	`FIREWORKS_API_KEY`	✅
Together	`langchain-together`	`TOGETHER_API_KEY`	❌
Mistral AI	`langchain-mistralai`	`MISTRAL_API_KEY`	✅
DeepSeek	`langchain-deepseek`	`DEEPSEEK_API_KEY`	✅
IBM (watsonx.ai)	`langchain-ibm`	`WATSONX_APIKEY`	❌
Nvidia	`langchain-nvidia-ai-endpoints`	`NVIDIA_API_KEY`	❌
xAI	`langchain-xai`	`XAI_API_KEY`	✅
Perplexity	`langchain-perplexity`	`PPLX_API_KEY`	✅
OpenRouter	`langchain-openrouter`	`OPENROUTER_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 标志在提供时始终优先。
~/.deepagents/config.toml 中的 [models].default —— 用户有意设置的长期偏好。
~/.deepagents/config.toml 中的 [models].recent —— 通过 /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

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

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

[models]
default = "ollama:qwen3:4b"        # your intentional long-term preference
recent = "anthropic:claude-sonnet-4-5"  # last /model switch (written automatically)

[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 以更早触发自动摘要——这对于测试或限制上下文使用量很有用：

# Apply to all models from this provider
[models.providers.anthropic.profile]
max_input_tokens = 4096

按模型子表的工作方式与 params 相同——发生冲突时模型级值优先：

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

# This model gets a higher limit
[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}'

# In non-interactive mode
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}'

# Combine with --model
deepagents --model anthropic:claude-sonnet-4-5 --profile-override '{"max_input_tokens": 4096}'

# In non-interactive mode
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:<model>`（内置，参见提供商参考）

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 环境中：

# If deepagents-cli was installed with uv tool:
uv tool upgrade deepagents-cli --with my_package

当你切换到 my_custom:my-model-v1（通过 /model 或 --model）时，模型名称（my-model-v1）会作为 model 关键字参数传递：

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 模型配置文件。

Edit this page on GitHub or file an issue.

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Get started

Core capabilities

Streaming

Protocols

Command line interface

快速开始

提供商参考

切换模型

设置默认模型

模型解析顺序

配置文件

示例

模型构造函数参数

按模型覆盖

配置文件覆盖

使用 `--model-params` 进行 CLI 覆盖

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

指定自定义 `base_url`

模型路由器和代理

兼容 API

向交互式切换器添加模型

任意提供商

Get started

Core capabilities

Streaming

Protocols

Command line interface

​快速开始

​提供商参考

​切换模型

​设置默认模型

​模型解析顺序

​配置文件

​示例

​模型构造函数参数

​按模型覆盖

​配置文件覆盖

​使用 --model-params 进行 CLI 覆盖

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

​指定自定义 base_url

​模型路由器和代理

​兼容 API

​向交互式切换器添加模型

​任意提供商

快速开始

提供商参考

切换模型

设置默认模型

模型解析顺序

配置文件

示例

模型构造函数参数

按模型覆盖

配置文件覆盖

使用 `--model-params` 进行 CLI 覆盖

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

指定自定义 `base_url`

模型路由器和代理

兼容 API

向交互式切换器添加模型

任意提供商