`（内置，参见[提供商参考](#provider-reference)） |
**OpenRouter** 是一个内置提供商——安装包后即可直接使用：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
uv tool install 'deepagents-cli[openrouter]'
```
**LiteLLM** 也是一个内置提供商：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
uv tool install 'deepagents-cli[litellm]'
```
## 切换模型
要在 CLI 中切换模型，可以：
1. **使用交互式模型切换器**，通过 `/model` 命令。这将显示来自每个已安装 LangChain 提供商包的[模型配置文件](/oss/python/langchain/models#model-profiles)的可用模型。
并非所有模型都会显示在此处。如果您的模型缺失，请直接传递模型名称（例如 `/model gpt-5.5`）。详情请参阅[哪些模型会出现在切换器中](#which-models-appear-in-the-switcher)。
2. **直接指定模型名称**作为参数，例如 `/model gpt-5.5`。您可以使用所选提供商支持的任何模型，无论它是否出现在选项 1 的列表中。模型名称将传递给 API 请求。
3. **在启动时指定模型**，通过 `--model`，例如
```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --model openai:gpt-5.5
```
当 CLI 启动时，它按以下顺序解析要使用的模型：
1. **`--model` 标志**在提供时始终优先。
2. `~/.deepagents/config.toml` 中的 **`[models].default`**——用户有意的长期偏好。
3. `~/.deepagents/config.toml` 中的 **`[models].recent`**——上次通过 `/model` 切换到的模型。自动写入；永远不会覆盖 `[models].default`。
4. **环境自动检测**：回退到第一个可用的启动凭据，按顺序检查：`OPENAI_API_KEY`、`ANTHROPIC_API_KEY`、`GOOGLE_API_KEY`、`GOOGLE_CLOUD_PROJECT`（Vertex AI）。
此启动回退有意仅检查这四个凭据。其他支持的提供商（例如 Groq）仍可通过 `--model`、`/model` 和保存的默认值（`[models].default` / `[models].recent`）使用。
### 哪些模型会出现在切换器中
`/model` 选择器根据已安装的提供商包动态构建其列表。展开下方查看完整标准和故障排除。
交互式 `/model` 选择器动态构建其列表——它不是硬编码在 CLI 中的列表。当满足以下**所有**条件时，模型会出现在切换器中：
1. **提供商包已安装。** 每个提供商（例如 `langchain-anthropic`、`langchain-openai`）必须与 `deepagents-cli` 一起安装——作为[安装附加组件](/oss/python/deepagents/cli/providers#quick-start)（例如 `uv tool install 'deepagents-cli[ollama]'`）或稍后使用 `uv tool install deepagents-cli --with ` 添加。如果缺少某个包，其整个提供商部分将不会出现在切换器中。
2. **模型具有启用 `tool_calling` 的配置文件。** CLI 需要工具调用支持，因此配置文件中没有 `tool_calling: true` 的模型将被排除。这是模型从列表中缺失的最常见原因。对于不捆绑配置文件的提供商（参见[提供商参考](#provider-reference)表），您可以在 `config.toml` 中定义一个：
```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[models.providers.ollama.profile."qwen3:4b"]
tool_calling = true
max_input_tokens = 32768
max_output_tokens = 8192
```
这对于模型出现在切换器中并非严格要求——将其添加到 [`models` 列表](/oss/python/deepagents/cli/configuration#adding-models-to-the-interactive-switcher)也可以，并且更简单。当您希望 CLI 了解模型的上下文窗口和功能（用于自动摘要等功能）时，配置文件很有用。有关所有可覆盖字段，请参阅[配置文件覆盖](/oss/python/deepagents/cli/configuration#profile-overrides-advanced)。
3. **模型接受并生成文本。** 配置文件中明确将 `text_inputs` 或 `text_outputs` 设置为 `false` 的模型（例如嵌入或图像生成模型）将被排除。
在 `config.toml` 的 [`[models.providers.].models`](/oss/python/deepagents/cli/configuration#adding-models-to-the-interactive-switcher) 下定义的模型会绕过配置文件过滤器——无论配置文件元数据如何，它们始终出现在切换器中。这是添加列表中缺失模型的推荐方式。
凭据状态**不会**影响模型是否被列出。切换器显示所有符合条件的模型，并在每个提供商标题旁显示凭据指示器：已确认凭据显示对勾，缺少凭据显示警告，凭据状态未知时显示问号。您仍然可以选择缺少凭据的模型——提供商将在请求时报告身份验证错误。
#### 故障排除：缺失模型
| 症状 | 可能原因 | 修复方法 |
| -------------- | --------------------------------------- | --------------------------------------------------------------------------------------------- |
| 整个提供商在切换器中缺失 | 提供商包未安装 | 安装该包（例如 `uv tool install deepagents-cli --with langchain-groq`） |
| 提供商显示但特定模型缺失 | 模型配置文件具有 `tool_calling: false` 或不存在配置文件 | 将模型添加到 `config.toml` 的 `[models.providers.].models` 中，或直接使用 `/model :` |
| 提供商显示 ⚠ “缺少凭据” | API 密钥环境变量未设置 | 设置[提供商参考](#provider-reference)表中的凭据环境变量 |
| 提供商显示 ? “凭据未知” | 提供商使用 CLI 无法验证的非标准身份验证 | 凭据可能仍然有效——尝试切换到该模型。如果身份验证失败，请检查提供商的文档 |
### 设置默认模型
您可以设置一个持久的默认模型，该模型将用于所有未来的 CLI 启动：
* **通过模型选择器：** 打开 `/model`，导航到所需模型，然后按 `Ctrl+S` 将其固定为默认值。再次按 `Ctrl+S` 可清除当前默认值。
* **通过命令：** `/model --default provider:model`（例如，`/model --default anthropic:claude-opus-4-6`）
* **通过配置文件：** 在 `~/.deepagents/config.toml` 中设置 `[models].default`（参见[配置](/oss/python/deepagents/cli/configuration)）。
* **通过 shell：**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --default-model anthropic:claude-opus-4-6
```
要查看当前默认值：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --default-model
```
要清除默认值：
* **通过 shell：**
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents --clear-default-model
```
* **通过命令：** `/model --default --clear`
* **通过模型选择器：** 在当前固定的默认模型上按 `Ctrl+S`。
如果没有默认值，CLI 将默认使用最近使用的模型。
### 模型参数
向模型传递额外的构造函数 kwargs——采样控制、推理/思考预算、上下文窗口大小、请求超时以及底层聊天模型类接受的任何其他参数。有三个地方可以设置它们，按优先级顺序（最高优先级在前）：
1. **启动时一次性使用 `--model-params`。** JSON 字符串，仅限会话：
```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# OpenAI 推理努力程度
deepagents --model openai:gpt-5.5 --model-params '{"reasoning": {"effort": "high"}}'
# Anthropic 扩展思考
deepagents --model anthropic:claude-opus-4-7 --model-params '{"thinking": {"type": "enabled", "budget_tokens": 10000}, "max_tokens": 16000}'
```
2. **会话中通过 `/model --model-params`。** 相同的 JSON 语法——无需重启即可交换参数（并可选地交换模型）：
```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
/model --model-params '{"temperature": 0.7}' anthropic:claude-opus-4-7
/model --model-params '{"num_ctx": 16384}' # 打开选择器，将参数应用于所选模型
```
3. **在 `config.toml` 中持久化。** 提供商级别的默认值（带有可选的每个模型子表），在每次启动时应用：
```toml theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
[models.providers.anthropic.params]
thinking = { type = "enabled", budget_tokens = 10000 }
max_tokens = 16000
[models.providers.openai.params]
reasoning = { effort = "high", summary = "auto" }
output_version = "responses/v1"
[models.providers.ollama.params]
num_ctx = 16384
temperature = 0
# 每个模型的覆盖——优先于提供商级别的键
[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5
```
CLI 标志会覆盖配置文件的 `params`，并且仅限会话（会话中的更改不会持久化）。`config.toml` 中的每个模型子表会覆盖提供商级别的键（浅层合并——完整语义请参阅[模型构造函数参数](/oss/python/deepagents/cli/configuration#model-constructor-params)）。`--model-params` 不能与 `--default` 组合使用。
底层聊天模型构造函数接受的任何 kwarg 都是有效的。有关完整列表，请参阅提供商的参考文档——例如 [`ChatAnthropic`](https://reference.langchain.com/python/langchain-anthropic/langchain_anthropic/chat_models/ChatAnthropic)、[`ChatOpenAI`](https://reference.langchain.com/python/langchain-openai/langchain_openai/chat_models/base/ChatOpenAI)、[`ChatOllama`](https://reference.langchain.com/python/langchain-ollama/langchain_ollama/chat_models/ChatOllama)。未知的 kwargs 会转发到上游 API 请求，因此新发布的参数无需 CLI 更新即可使用。
不要在 `params` 中放置凭据（`api_key`）——请使用 [`api_key_env`](/oss/python/deepagents/cli/configuration#provider-configuration) 指向环境变量。
要覆盖模型运行时*配置文件*上的字段（`max_input_tokens`、`tool_calling`、功能标志）——与构造函数参数不同——请参阅[配置文件覆盖](/oss/python/deepagents/cli/configuration#profile-overrides-advanced)。
## 高级配置
有关提供商参数、配置文件覆盖、自定义基础 URL、兼容 API、任意提供商和生命周期钩子的详细配置，请参阅[配置](/oss/python/deepagents/cli/configuration)。
***
[将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
[在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/providers.mdx) 或 [提交问题](https://github.com/langchain-ai/docs/issues/new/choose)。