LangChain 中文文档

外观

~/.deepagents/config.toml 让你可以自定义模型提供商、设置默认值，并向模型构造函数传递额外参数。关于环境变量与检查命令，参见 配置。本页面涵盖：

默认与最近使用的模型 ​

toml
[models]
default = "ollama:qwen3:4b"             # 你有意设定的长期偏好
recent = "google_genai:gemini-3.6-flash"   # 最后一次 /model 切换（自动写入）

[models].default 始终优先于 [models].recent。/model 命令只写入 [models].recent，因此你配置的默认模型永远不会被会话中的切换覆盖。要移除默认模型，请使用 /model --default --clear 或删除配置文件中的 default 键。

默认与最近使用的智能体 ​

toml
[agents]
default = "backend-dev"  # 你有意设定的长期偏好（在 /agents 选择器中按 Ctrl+S）
recent = "frontend-dev"  # 最后一次 /agents 切换（自动写入）

[agents].default 始终优先于 [agents].recent。在 /agents 选择器中用 Enter 选中智能体会写入 recent；在选中行按 Ctrl+S 会将其固定为 default。再次在同一行按 Ctrl+S 会清除默认值。

显式的 -a/--agent 始终覆盖两者，而 -r/--resume 会绕过两者，从而恢复该线程原本的智能体。相关标志参见 命令参考。

脱敏 LangSmith 追踪中的机密 ​

启用 LangSmith 追踪后，默认情况下 Deep Agents Code 会在不进行客户端机密脱敏的情况下发送智能体追踪的输入与输出。

WARNING

如果不脱敏，机密可能会作为智能体追踪的一部分被上传到 LangSmith。

要在上传前对检测到的机密进行脱敏：

配置文件 ​

toml
[tracing]
langsmith_redact = true

环境变量 ​

bash
export DEEPAGENTS_CODE_LANGSMITH_REDACT=true

环境变量优先于配置文件。启用脱敏后，如果无法配置脱敏，Deep Agents Code 会为此次运行禁用追踪。机密脱敏不会脱敏一般性的个人身份信息（PII）、追踪元数据，或由 shell 进程发出的追踪。更广泛的选择参见 从追踪中脱敏机密。

提供商配置 ​

每个提供商都是 [models.providers] 下的一个 TOML 表：

toml
[models.providers.<name>]
display_name = "My Provider"
api_key_url = "https://provider.example/keys"
models = ["gpt-5.5"]
api_key_env = "OPENAI_API_KEY"
base_url = "https://api.openai.com/v1"
class_path = "my_package.models:MyChatModel"
enabled = true

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

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

提供商有以下配置选项：

  • models (string[])：要在交互式 /model 切换器中为定义为 <name> 的提供商显示的模型名称列表。对于已经随包内置模型配置档案的提供商，你在这里添加的任何名称都会与内置模型一并显示（这对于尚未添加到包中的新发布模型很有用）。对于任意提供商，此列表是切换器中模型的唯一来源。 列在此处的模型会绕过任何基于配置档案的过滤条件，始终出现在切换器中。因此，这是让因配置档案缺少 tool_calling 支持或尚无配置档案而被排除的模型得以显示的推荐方式。 此键是可选的。无论模型是否出现在切换器中，你都可以随时把任何模型名称直接传给 /model 或 --model；提供商会在请求时校验该名称。

  • api_key_env (string)：持有 API 密钥的环境变量的名称（例如 "OPENAI_API_KEY"）。Deep Agents Code 在启动时从该环境变量读取凭据，以在创建模型前验证访问权限。 大多数对话模型包会自动从默认环境变量读取。每个内置提供商检查哪个变量名，参见 提供商参考 表格。对于不在该表格中的提供商，请把 api_key_env 设置为其变量名（参见 任意提供商）。

  • display_name (string)：在认证界面中显示的人类可读提供商名称。对于配置键面向机器优化的任意提供商（例如 my_gateway），但其界面标签应包含空格或品牌大小写时，请使用此字段。

  • api_key_url (string)：用户创建或管理 API 密钥的提供商页面 URL。/auth 弹窗会在 API 密钥输入框之前链接到该页面。此值是 URL，不是凭据。

  • base_url (string)：在受支持的情况下覆盖提供商使用的 base URL。更多信息请参阅提供商包的参考文档。 将内置提供商指向线路兼容的端点参见 兼容 API，通过 class_path 配置的提供商参见 任意提供商。

  • base_url_env (string)：持有该提供商 base URL 的环境变量名称，与 api_key_env 平行。当端点来自环境而不是固定值时——例如因机器或 CI 作业而不同的网关 URL——请使用此字段而不是 base_url，这样无需编辑 config.toml 即可更改，并且可以参与端点解析和密钥/端点配对（参见 端点、密钥与网关）。它还把这一机制扩展到内置集合之外的提供商；参见 任意提供商。 如果两者都设置了，静态的 base_url 优先： toml [models.providers.example] base_url = "https://fixed.example/v1" # 使用 base_url_env = "EXAMPLE_BASE_URL" # 在设置 base_url 时被忽略

  • params (object)：转发给模型构造函数的额外关键字参数。扁平键（例如 temperature = 0）适用于该提供商的所有模型。按模型键控的子表（例如 [params."gpt-5.5"]）仅覆盖该模型的个别值；合并是浅合并（冲突时模型层获胜）。 不要把凭据（例如 api_key）放在 params 中。请改用 api_key_env 指向环境变量。

  • profile (object)：（高级）覆盖模型运行时配置档案中的字段（例如 max_input_tokens）。扁平键适用于该提供商的所有模型。按模型键控的子表（例如 [profile."claude-sonnet-4-5"]）仅覆盖该模型的个别值；合并是浅合并（冲突时模型层获胜）。这些覆盖在模型创建后应用，因此对上下文限制显示、自动摘要以及任何读取配置档案的功能都会生效。示例与 --profile-override 标志参见 配置档案覆盖。

  • class_path (string)：用于任意模型提供商。采用 module.path:ClassName 格式的完全限定 Python 类。设置后，Deep Agents Code 会为提供商 <name> 直接导入并实例化该类。该类必须是 BaseChatModel 的子类。

  • enabled (boolean)（默认：true）：该提供商是否出现在 /model 选择器中。设置为 false 可以隐藏从已安装包自动发现的提供商（例如你不想让模型切换器显得杂乱的一个传递依赖）。你仍然可以通过 /model provider:model 或 --model 直接使用被禁用的提供商。

模型构造函数参数 ​

params 字段会把额外参数转发给模型构造函数。要给某个模型不同的值，请添加一个按模型键控的子表，这样就不必复制整个提供商配置：

toml
[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} —— 无覆盖，仅使用提供商级参数。

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

TIP

如需一次性调整而不编辑 config.toml，可以在启动时或会话中通过 /model 传入一个 JSON 对象，使用 --model-params。CLI 标志的优先级高于配置文件。语法与提供商专属示例参见提供商页面的 模型参数。

重试 ​

使用顶层的 [retries] 节配置针对模型提供商瞬时错误的重试次数。Deep Agents Code 会把这些值传递给接受重试次数构造函数关键字参数的提供商集成。如果省略该节，则使用提供商 SDK 默认值。

toml
[retries]
max_retries = 2

[retries.fireworks]
max_retries = 3

[retries.anthropic]
max_retries = 0

全局的 [retries].max_retries 值适用于所有受支持的提供商。提供商专属的表（例如 [retries.fireworks]）会覆盖该提供商的全局值。值必须是大于或等于 0 的整数。

大多数受支持的提供商会把重试次数作为 max_retries 接收。有些集成使用不同的构造函数关键字参数。对于任意提供商，或要覆盖已知提供商的已注册关键字参数，请在提供商专属重试表中设置 param：

toml
[retries]
max_retries = 2

[retries.my_custom]
param = "retries"
max_retries = 4

param 必须是合法的 Python 标识符字符串，例如 "max_retries" 或 "retries"。Deep Agents Code 会忽略未设置 param 的未知提供商，因为传递错误的重试关键字参数可能会破坏模型创建。

[retries] 的优先级低于构造函数参数。完整优先级顺序为：

  1. --max-retries N，在提供商解析出的重试关键字参数下应用
  2. 携带提供商重试关键字参数的 --model-params，例如 '{"max_retries": N}' 或 '{"retries": N}'
  3. 携带提供商重试关键字参数的 [models.providers.<provider>.params]
  4. [retries.<provider>].max_retries
  5. [retries].max_retries
  6. 提供商 SDK 默认值

启动审批模式 ​

用顶层的 [startup].mode 键设置交互式会话的默认审批模式：

toml
[startup]
mode = "auto"   # "manual"（默认）、"auto" 或 "yolo"

可接受的值有 manual（默认，失败即关闭）、auto（基于分类器；需要 DEEPAGENTS_CODE_EXPERIMENTAL=1）和 yolo（不受限；需要一次性确认）。显式的 --yolo 或 -y/--auto-approve 标志会为本次会话覆盖此值。

配置档案覆盖（高级） ​

覆盖模型运行时配置档案中的字段，可以改变 Deep Agents Code 对模型能力的解读方式。可覆盖字段的完整列表参见 ModelProfile。最常见的用例是调低 max_input_tokens 以便更早触发自动摘要——适合测试或约束上下文使用：

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

按模型的子表与 params 的工作方式相同——冲突时模型级值获胜：

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

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

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

使用 --profile-override 的 CLI 配置档案覆盖 ​

要在运行时覆盖模型配置档案字段而不编辑配置文件，请传入一个 JSON 对象作为 `--profile-override`：
bash
dcode --profile-override '{"max_input_tokens": 4096}'

# 与 --model 结合使用
dcode --model google_genai:gemini-3.6-flash --profile-override '{"max_input_tokens": 4096}'

# 在非交互模式下
dcode -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'
这些值会合并到配置文件档案覆盖之上（CLI 优先）。优先级链为：模型默认 &lt; config.toml 配置档案 &lt; CLI `--profile-override`。

`--profile-override` 的值会在会话中的 `/model` 热切换之后保留——切换模型时覆盖会重新应用到新模型。

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

有些提供商（例如 langchain-ollama）不内置模型配置档案数据（完整清单参见 提供商参考）。在这种情况下，交互式 /model 切换器不会为该提供商列出模型。你可以通过在配置文件中为该提供商定义一个 models 列表来填补这个空缺：

toml
[models.providers.ollama]
models = ["gemma4", "qwen3.6", "granite4.1:3b"]

现在 /model 切换器将包含一个列出这些模型的 Ollama 小节。

这完全可选。你始终可以直接指定完整名称切换到任何模型：

txt
/model ollama:qwen3.6:27b

INFO

当 langchain-ollama 已安装且守护进程可达时，Deep Agents Code 会自动发现本地拉取的模型并将其合并到切换器中——无需 models 列表。拉取新模型后运行 /reload 刷新，或设置 DEEPAGENTS_CODE_OLLAMA_DISCOVERY=0 选择退出。

自定义 base URL ​

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

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

兼容性信息与其它注意事项请参阅提供商的参考文档。

兼容 API ​

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

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

INFO

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

WARNING

OpenAI 提供商默认使用 Responses API，大多数与 OpenAI 兼容的网关并不实现它。如果你的提供商只支持 Chat Completions API，调用很可能会失败。请显式禁用 Responses API：

toml
[models.providers.openai.params]
use_responses_api = false

任意提供商 ​

Deep Agents Code 适用于任何以 LangChain BaseChatModel 形式提供的、支持工具调用的大语言模型。内置提供商开箱即用；较少见或自研的模型则需要多一点设置。把 class_path 指向其 BaseChatModel 子类，Deep Agents Code 就会直接导入并实例化该类。

toml
[models.providers.my_custom]
display_name = "My Custom Provider"
api_key_url = "https://my-provider.example.com/keys"
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

api_key_env 和 base_url 是可选的。display_name 和 api_key_url 用于自定义 /auth 显示的提供商名称与密钥获取链接；省略它们则回退到提供商配置键与提供商设置文档。要从环境变量读取端点而不是硬编码 base_url，请使用 base_url_env；它会像内置提供商一样解析并与密钥配对（参见 端点、密钥与网关）。

class_path 提供商应自行处理认证——当你的模型使用自定义认证（JWT token、专有请求头、mTLS 等）而不是标准 API 密钥时这很有用：

toml
[models.providers.xyz]
class_path = "abc.integrations.deepagents:DeepAgentsXYZChat"
models = ["abc-xyz-1"]

[models.providers.xyz.params]
bypass_auth = true
temperature = 0

使用此配置，可通过 /model xyz:abc-xyz-1 或 --model xyz:abc-xyz-1 切换到该模型。

INFO

Deep Agents Code 要求支持工具调用。如果你的自定义模型支持工具调用但 Deep Agents Code 不知道，请在提供商配置档案中声明它：

toml
[models.providers.xyz.profile]
tool_calling = true
max_input_tokens = 128000

虽然可选，但强烈建议把 max_input_tokens 设置为你模型的上下文窗口。不设置的话，Deep Agents Code 无法显示上下文已满的程度，自动摘要会回退到固定触发值（约 170,000 token），而不是你模型窗口的一定比例。对于窗口较小的模型，摘要可能在你达到模型的硬性限制之前都不会运行，因此随着对话增长，请求会开始失败。

因为 Deep Agents Code 在启动时导入 class_path 类，定义它的包必须能从运行 dcode 的同一环境中导入。内置提供商随安装附加项一起提供，但自定义或自研包不在其中。使用 --package 标志把它安装到 dcode 环境中：

bash
dcode --install my_package --package

在会话中运行 /install my_package --package --force。两者都会把包与 dcode 一起安装。如果包缺失或无法导入，Deep Agents Code 会跳过该提供商，其模型也不会出现在 /model 中。

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

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

WARNING

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

你的提供商包还可以在 <package>.data._profiles 中以 _PROFILES 字典的形式提供模型配置档案，以代替在 models 键下定义它们。更多信息参见 LangChain 模型配置档案。

端点、密钥与网关 ​

API 密钥与其发送到的端点必须匹配：端点必须接受该密钥，否则请求很可能会失败。Deep Agents Code 会把密钥与端点一起解析，因此覆盖其中一个会更新另一个以保持匹配。例如，如果你用你自己的密钥替换网关供应的密钥，Deep Agents Code 也会丢弃网关端点，这样你的密钥会直接发给提供商，而不是发给一个会拒绝它的网关。

base_url 如何解析 ​

Deep Agents Code 按以下顺序解析提供商的端点（第一个匹配项生效）：

  1. config.toml 中该提供商的 base_url。
  2. 带 DEEPAGENTS_CODE_ 前缀的端点变量。
  3. 环境中的普通端点变量（例如 OPENAI_BASE_URL）。
  4. 与 /auth 凭据一起保存的端点。 此步骤会对没有端点变量的提供商应用已保存的端点——例如你在未声明 base_url_env 的情况下添加的提供商。对于这些提供商，步骤 2-3 没有变量可读，因此这里直接使用已保存的端点。对于确实有端点变量的提供商，已保存的端点已经在步骤 2 或 3 生效（它会写入该变量），因此此步骤不改变任何内容。无论哪种情况，在 /auth 中输入的端点都会生效。
  5. 提供商 SDK 自身的默认端点，当以上均未设置时。

INFO

解析出的端点会作为 base_url 构造函数参数传递给模型。

与 API 密钥一样，DEEPAGENTS_CODE_ 前缀会把端点的作用域限定为 Deep Agents Code，而不影响其他工具。对于任何其他提供商，用 base_url_env 声明名称，端点就会以相同方式解析并配对：

toml
[models.providers.myprovider]
api_key_env = "MYPROVIDER_API_KEY"
base_url_env = "MYPROVIDER_BASE_URL"
models = ["my-model"]

字面量 base_url 优先于 base_url_env，因此只设置你需要的那个：

toml
[models.providers.myprovider]
base_url = "https://fixed.example/v1"   # 使用
base_url_env = "MYPROVIDER_BASE_URL"    # 在设置 base_url 时被忽略

覆盖会让这一对保持在一起 ​

当你用 /auth 存储一个密钥时，你输入的端点（如果留空则使用提供商默认值）会与密钥一起应用。使用空 base URL 存储密钥，还会清除你环境中已设置的任何端点（例如你的 shell 导出的网关 OPENAI_BASE_URL），这样你的密钥会发给提供商的默认端点，而不是发给那个网关。

bash
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-cli-only
DEEPAGENTS_CODE_OPENAI_BASE_URL=https://api.openai.com/v1

受管网关 ​

在一台配置了模型网关（例如 LangSmith 网关）的机器上，网关通常会一起导出网关密钥与匹配的端点变量（OPENAI_BASE_URL、ANTHROPIC_BASE_URL 或 GOOGLE_GEMINI_BASE_URL）。Deep Agents Code 默认使用这一对，因此无需配置。

要改用自己的密钥，请用 /auth 存储它（base URL 留空以使用提供商默认值，或显式设置），或设置带 DEEPAGENTS_CODE_ 前缀的密钥与端点。两者都会覆盖网关这一对，且不会留下不匹配的端点。

智能体运行时限制 ​

LangGraph 图步骤预算是 dcode 智能体图在单轮中可以执行的最大节点调用次数。使用 [runtime] 节配置此递归限制：

toml
[runtime]
recursion_limit = 2000

默认值为 2000。有效值是 25 到 100000（含）之间的整数。超出此范围的值或非整数值会记录警告并回退到默认值。

优先级（从高到低）：

  1. --recursion-limit CLI 标志
  2. DEEPAGENTS_CODE_RECURSION_LIMIT 环境变量
  3. config.toml 中的 [runtime].recursion_limit
  4. 内置默认值（2000）

使用 dcode config get runtime.recursion_limit 查看有效值及其来源。

CLI 标志 ​

bash
dcode --recursion-limit 5000

环境变量 ​

bash
export DEEPAGENTS_CODE_RECURSION_LIMIT=5000

配置文件 ​

toml
[runtime]
recursion_limit = 5000

INFO

goal_rubric 的递归限制是独立的，不受此设置影响。

另请参阅 ​