`（内置，参见[提供商参考](#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#quickstart)（例如 `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 :` |
| 提供商显示 ⚠ "missing credentials" | API 密钥环境变量未设置 | 从[提供商参考](#provider-reference)表设置凭证环境变量 |
| 提供商显示 ? "credentials unknown" | 提供商使用 CLI 无法验证的非标准认证 | 凭证可能仍然有效 — 尝试切换到该模型。如果认证失败，检查提供商的文档 |
### 设置默认模型
你可以设置一个持久的默认模型，用于所有未来的 CLI 启动：
* **通过模型选择器：** 打开 `/model`，导航到所需模型，按 `Ctrl+S` 将其固定为默认值。再次在当前默认值上按 `Ctrl+S` 清除它。
* **通过命令：** `/model --default provider:model`（例如 `/model --default anthropic:claude-opus-4-7`）
* **通过配置文件：** 在 `~/.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-7
```
查看当前默认值：
```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 将默认使用最近使用的模型。
### 模型参数
向模型传递额外的构造关键字参数 — 采样控制、推理/思考预算、上下文窗口大小、请求超时以及底层聊天模型类接受的任何其他参数。三个设置位置，按优先级排序（从高到低）：
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` 组合。
底层聊天模型构造函数接受的任何关键字参数都是有效的。参阅提供商的参考文档了解完整列表 — 例如 [`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)。未知的关键字参数被转发到上游 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)。