配置文件

在 config.toml 中配置模型服务商、默认值、重试和网关

你可以通过 ~/.deepagents/config.toml 自定义模型服务商、设置默认值，并向模型构造函数传入额外参数。关于环境变量和查看命令，参见配置。本页涵盖以下内容：

• 默认值：固定默认模型、摘要模型或智能体，或用允许列表限制可用模型。
• 警告：会话成本阈值、缓存过期提示以及受信任的网关端点。
• 显示：服务商可见的推理内容和 diff 行号。
• 线程：针对过期对话的恢复限制。
• 解释器：内置 QuickJS REPL 的 [interpreter] 设置。
• Python 扩展：自定义工具、middleware 和存储路由的发现与项目信任。
• 追踪：针对 LangSmith trace 的客户端密钥脱敏。
• 服务商设置：[models.providers.<name>] 表、构造函数参数、重试、profile 覆盖，以及向 /model 切换器添加模型。
• Auto 模式：自动分类器超时。
• 自定义端点与服务商：自定义 base URL、兼容 OpenAI 或 Anthropic 的 API，以及任意服务商。
• 端点与网关：API 密钥与 base URL 如何一起解析，包括经由托管网关的情况。

默认模型与最近使用的模型

[models]
default = "ollama:qwen3:4b"             # your intentional long-term preference
recent = "google_genai:gemini-3.6-flash"   # last /model switch (written automatically)
auto_classifier = "openai:gpt-5.6-luna"  # optional: cheaper model for Auto approval review

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

[models].auto_classifier 用于设置自动审批分类器在审查受控工具调用时使用的模型。未设置时，Deep Agents Code 会为受支持的主模型服务商选择延迟更低的默认值：Anthropic 使用 Claude Sonnet，Google 使用 Gemini Flash，OpenAI 使用 GPT Luna。其他服务商继承主智能体模型。你可以在运行时通过 --auto-classifier-model 或 /auto model 覆盖该设置。关于确切的模型规格、完整优先级以及安全说明，参见选择分类器模型。

设置摘要模型

为自动上下文压缩、/offload 和 /compact 设置专用模型：

[models]
summarization_default = "openai:gpt-5.6-sol"

摘要模型按以下顺序解析：

1. --summarization-model：用于本次启动。
2. [models].summarization_default。
3. 主智能体模型。

在交互式会话中，运行 /summarization-model 可打开模型选择器；/summarization-model <provider:model> 可直接切换；/summarization-model clear 则重新跟随主智能体模型。更改摘要模型不会更改主智能体模型。

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

[agents]
default = "backend-dev"  # your intentional long-term preference (Ctrl+S in /agents picker)
recent = "frontend-dev"  # last /agents switch (written automatically)

[agents].default 的优先级始终高于 [agents].recent。在 /agents 选择器中按 Enter 选中某个智能体会写入 recent；在突出显示的行上按 Ctrl+S 会将其固定为 default。在同一行上再次按 Ctrl+S 会清除该默认值。

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

会话成本警告

当某个线程的累计估算成本超过 $50 时，Deep Agents Code 会在该线程中发出一次警告，并建议使用 /offload 或 /clear。你可以以美元为单位配置该阈值，或者将其设为 0 或负值以禁用该警告：

[warnings]
session_cost_threshold_usd = 25

冷提示词缓存警告

当服务商的缓存保留窗口到期后，缓存提示会让你在「开启一个经过摘要的线程」和「继续当前对话」之间做出选择。Deep Agents Code 会跟踪受支持的 Anthropic 和 OpenAI 模型的保留时长。在能够获取到定价信息时，它会显示继续对话的估算输入成本，以及与命中温缓存相比的额外成本。

计时器到期后继续

默认情况下，当页脚的缓存保留计时器归零且 Deep Agents Code 处于空闲状态时，该提示会弹出。当智能体正在工作或有其他模态框打开时，它会等待。计时器归零表示可能发生缓存未命中，但并不保证一定发生。

提示弹出时，选择继续的方式：

• 按 Enter 开启经过摘要的线程：Deep Agents Code 会使用你的摘要模型对对话进行摘要，并开启一个新线程。新线程包含摘要内容、原始线程 ID，以及一个用于恢复摘要中省略细节的转储文件路径。原始线程保留其完整的消息，并仍可通过 /threads 访问。
• 按 Esc 留在当前线程：Deep Agents Code 会保留你的草稿而不发送。对于同一个缓存窗口，你的下一次显式发送不会再触发过期警告。

这两种选择都不会发送你的草稿。准备好继续时再提交即可。摘要会产生一次付费的模型调用，并不保证能节省成本。如果摘要失败，Deep Agents Code 会让你留在原始线程中。

转储文件路径指向智能体的文件系统。归档文件遵循对话历史保留策略，临时存储可能无法在重启后保留。如果归档不可用，可使用 /threads 恢复原始对话。

与过期提示中的新建线程操作不同，/offload（别名 /compact）是在当前线程内释放上下文空间。

选择提示时机

在 /config 中设置 warnings.cache_prompt，或编辑 ~/.deepagents/config.toml：

[warnings]
cache_prompt = "expiry"

• "expiry"（默认）：当缓存计时器到期且应用处于空闲状态时显示提示。如果你在提示出现之前就提交，则在发送之前显示提示。
• "send"：等到到期后你提交消息时，再显示同样的提示。Esc 会恢复已提交的草稿而不发送；再次提交即可在当前线程中继续。Enter 会打开经过摘要的线程，并在其中恢复草稿供你提交。
• "off"：禁用缓存提示，包括发送时的缓存成本确认。这不会禁用独立的会话成本警告。

这些设置适用于交互式对话，不适用于 headless 模式。除非你显式设置了 warnings.cache_prompt，否则旧的首选项 warnings.cache_expiry_prompt = false 会映射为 "send"。

设置发送时成本阈值

无论估算成本如何，过期提示都会出现。如果无法获得估算值，提示会明确说明这一点，而不是假定下一轮不会产生成本。

模型、端点或缓存设置的更改仍可能触发独立的发送时成本确认。确认过期提示并不会抑制这些警告。该确认同样涵盖缓存时长未知的情况，例如没有记录请求时间的较旧线程。

为这些发送时确认设置触发所需的最小额外估算成本（以美元计）。默认值为 0.50；设为 0 或负值会禁用它们，但不会禁用过期提示。使用 cache_prompt = "off" 可同时禁用两者：

[warnings]
cold_cache_min_delta_usd = 1.00

发送时成本确认提供以下选项：

• 仍然发送：发送本轮，并在后续轮次中保持警告开启。
• 发送且本次会话不再警告：在应用重启之前不再提示发送时成本确认。
• 发送且不再警告：持久性地抑制发送时成本确认。可通过 /notifications 重新启用。
• 不发送（保留草稿）：将消息恢复到聊天输入框而不发送。

这些通知选项不会禁用过期提示。请使用 warnings.cache_prompt 来控制该流程。

为缓存策略信任某个网关端点

如果请求是经由网关或代理而非官方 API 到达服务商，冷缓存警告将保持静默。将某个端点声明为受信任，即表示你确认它会原样转发缓存设置，并遵循服务商文档所记载的保留策略：

[warnings]
trusted_cache_endpoints = ["smith.langchain.com"]

条目是按精确匹配的主机名——信任 example.com 并不会信任 gw.example.com。一条条目覆盖经由该端点路由的所有服务商。通过 LangSmith Gateway 的跨格式路由（例如以 OpenAI 格式发出的请求被路由到 Anthropic 模型）即使在受信任的情况下也保持静默，因为格式转换会重写估算所依据的缓存设置。

显示服务商可见的推理内容

默认情况下，服务商可见的推理内容是隐藏的。要在交互式转储记录和非交互式输出中显示它，请设置：

[ui]
show_reasoning = true

在交互式会话中，推理内容会流式输出到单独的一行，该行在阶段结束时折叠。点击该行或按 Ctrl+O 可重新展开。在非交互式模式下，推理内容输出到 stderr，以便 stdout 上的最终答案仍可被管道接收。

设置 DEEPAGENTS_CODE_SHOW_REASONING=1 可覆盖 config.toml，或传入 --show-reasoning 为单次启动启用该设置。启动标志的优先级高于环境变量，而环境变量的优先级高于 config.toml。

NOTE

Deep Agents Code 只会显示模型服务商所公开的推理内容。经过脱敏或不透明的推理内容仍保持隐藏。

Diff 行号

默认情况下，Deep Agents Code 会在转储记录和审批 diff 中显示相对于文件的行号。要隐藏它们，请设置：

[ui]
show_diff_line_numbers = false

在会话中运行 /line-numbers 可切换该首选项并将其保存到 config.toml。该更改只应用于新的 diff；已经渲染的 diff 不会改变。

限制线程可恢复的时长

限制用户可以恢复哪些已保存的线程，以防止旧对话在模型或策略变更后恢复过时的上下文。

使用 threads.max_resume_age 设置滚动的最大时长：

[threads]
max_resume_age = "7d"

该值必须是一个正整数，后接以下时长后缀之一：s 表示秒，m 表示分钟，h 表示小时，d 表示天，w 表示周。

对于固定的迁移或策略边界，可将 threads.resume_after 设置为 ISO 8601 日期或带时区的日期时间。日期采用 UTC 午夜零点：

[threads]
resume_after = "2025-06-01T00:00:00Z"

当你同时设置这两个选项时，Deep Agents Code 会采用较晚、也就是更严格的截止时间。该限制适用于以下场景：启动时恢复、在会话中恢复或切换线程、选中某个线程，或切换到属于另一个智能体的线程。如果某个已保存线程的最后更新时间戳缺失或无效，则在任一限制生效期间，Deep Agents Code 会阻止该恢复操作。

管理员可以在 managed_config.toml 中强制实施其中任一选项。无效的托管值会导致启动中止，而不会回退到用户配置。

允许的模型

使用 [models].allowed 列表将 dcode 限制在已批准的模型集合内：

[models]
allowed = ["anthropic:claude-fable-5", "openai:*"]

条目可以是精确的 provider:model 规格，也可以是 provider:* 通配符，用于放行某个服务商的全部型号。设置该列表后，被阻止的模型会从 /model 切换器中隐藏，并且在其他地方被选中时会被拒绝。

当该键未设置时，所有模型都是允许的。显式的空列表则表示一个都不允许：

[models]
allowed = []   # no model may be used

通配符会包含从内置服务商 profile 中发现的模型，或你所配置的 models 列表中的模型。如果该服务商没有任何可用模型，则该通配符不允许任何模型。

允许 Amazon Bedrock 模型

Bedrock 的模型 ID 请写作 bedrock:<id>，并包含 ID 中的版本冒号：

[models]
allowed = ["bedrock:anthropic.claude-3-5-sonnet-20241022-v2:0"]

对 LangSmith trace 中的密钥进行脱敏

启用 LangSmith 追踪后，Deep Agents Code 会在上传之前对智能体 trace 的输入和输出中检测到的密钥进行脱敏。该功能默认启用。

要禁用脱敏：

[tracing]
langsmith_redact = false

环境变量的优先级高于配置文件。当脱敏处于启用状态时，如果无法配置脱敏，Deep Agents Code 会在本次运行中禁用追踪。密钥脱敏不会对一般性的个人身份信息（PII）、trace 元数据或由 shell 进程发出的 trace 进行脱敏。更多选项参见对 trace 中的密钥进行脱敏。

服务商配置

每个服务商都是 [models.providers] 下的一个 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

服务商具有以下配置选项：

string[]

一个模型名称列表，用于在交互式 /model 切换器中显示定义为 <name> 的服务商。对于已经内置模型 profile 的服务商，你在此处添加的任何名称都会在内置模型之外额外显示（对于尚未被加入包中的新发布模型很有用）。对于任意服务商，该列表是切换器中模型的唯一来源。

此处列出的模型会绕过任何基于 profile 的筛选条件，始终出现在切换器中。因此，对于那些因为 profile 缺少 tool_calling 支持或 profile 尚不存在而被排除的模型，这是让它们显现出来的推荐方式。

该键是可选的。无论某个模型是否出现在切换器中，你都可以直接将任意模型名称传给 /model 或 --model；服务商会在请求时校验该名称。

string

保存 API 密钥的环境变量名称（例如 "OPENAI_API_KEY"）。Deep Agents Code 会在启动时从该环境变量读取凭据，以便在创建模型之前验证访问权限。

大多数聊天模型包会自动从默认的环境变量读取。关于每个内置服务商会检查哪个变量名，参见服务商参考表格。对于不在该表格中的服务商，请将 api_key_env 设为其变量名（参见任意服务商）。

string

在认证 UI 中显示的可读服务商名称。适用于这样一类任意服务商：其配置键为机器可读性而优化（例如 my_gateway），但 UI 标签需要包含空格或品牌大小写形式。

string

供用户创建或管理 API 密钥的服务商页面 URL。/auth 模态框会在 API 密钥输入框之前链接到该页面。该值是一个 URL，而不是凭据。

string

在支持的情况下，覆盖服务商所使用的 base URL。更多信息请参阅你的服务商包的参考文档。

关于将内置服务商指向线路兼容的端点，参见兼容 API；关于通过 class_path 配置的服务商，参见任意服务商。

string

保存该服务商 base URL 的环境变量名称，与 api_key_env 相对应。当端点来自环境而不是固定值时——例如因机器或 CI 任务而异的网关 URL——应当使用它而非 base_url，这样端点无需编辑 config.toml 就能变化，并且可以参与端点解析以及密钥与端点的配对（参见端点、密钥与网关）。它还会把这些能力扩展到内置集合之外的服务商；参见任意服务商。

如果两者都设置了，则以静态的 base_url 为准：

[models.providers.example]
base_url = "https://fixed.example/v1"   # used
base_url_env = "EXAMPLE_BASE_URL"        # ignored while base_url is set

object

转发给模型构造函数的额外关键字参数。扁平键（例如 temperature = 0）适用于该服务商的每一个模型。以模型为键的子表（例如 [params."gpt-5.5"]）仅覆盖该模型的相应值；合并是浅层的（冲突时以模型为准）。

不要将凭据（例如 api_key）放入 params。请改用 api_key_env 指向某个环境变量。

object

（高级）覆盖模型运行时 profile 中的字段（例如 max_input_tokens）。扁平键适用于该服务商的每一个模型。以模型为键的子表（例如 [profile."claude-sonnet-4-5"]）仅覆盖该模型的相应值；合并是浅层的（冲突时以模型为准）。这些覆盖会在模型创建之后应用，因此它们对上下文上限显示、自动摘要以及任何其他读取 profile 的功能都会生效。示例以及 --profile-override 标志参见 Profile 覆盖。

string

用于任意模型服务商。以 module.path:ClassName 格式表示的完全限定 Python 类。设置后，Deep Agents Code 会直接为服务商 <name> 导入并实例化该类。该类必须是 BaseChatModel 的子类。

boolean默认 true

该服务商是否出现在 /model 选择器中。设为 false 可隐藏某个从已安装包中自动发现的服务商（例如你不想让它扰乱模型切换器的传递依赖）。你仍然可以通过 /model provider:model 或 --model 直接使用已被禁用的服务商。

模型构造函数参数

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} —— 没有覆盖，只有服务商级别的 params。

合并是浅层的：模型子表中出现的任何键都会替换服务商级别 params 中的同名键，而仅存在于服务商级别的键会被保留。

TIP

若要在不编辑 config.toml 的情况下做一次性调整，可在启动时或会话中途通过 /model 传入 --model-params 的 JSON 对象。CLI 标志的优先级高于配置文件。语法以及各服务商的示例，参见服务商页面上的模型参数。

重试

Deep Agents Code 会在模型节点处重试暂时性的模型错误。默认值是在首次请求之后重试五次。设置顶层的 [retries] 值可更改重试预算，或将其设为 0 以禁用重试：

[retries]
max_retries = 2

[retries.fireworks]
max_retries = 3

[retries.anthropic]
max_retries = 0

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

对于任意服务商，可将 param 设为其重试次数构造函数参数的名称。Deep Agents Code 仅使用 param 来禁用服务商 SDK 的重试循环，从而让模型节点的 middleware 成为所配置重试预算的唯一掌控者：

[retries]
max_retries = 2

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

param 必须是有效的 Python 标识符字符串，例如 "max_retries" 或 "retries"。它并不设置重试预算。请通过本节中的 max_retries 或 --max-retries 来设置预算。

重试预算的优先级顺序如下：

1. --max-retries N
2. [retries.<provider>].max_retries
3. [retries].max_retries
4. Deep Agents Code 默认值（5）

启动时的审批模式

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

[startup]
mode = "auto"   # "manual" (default), "auto", or "yolo"

可接受的值包括 manual（默认值，失败即关闭）、auto（由分类器支持；需要 DEEPAGENTS_CODE_EXPERIMENTAL=1）和 yolo（无限制；需要一次性确认）。显式的 --yolo 或 -y/--auto-approve 标志会在本次会话中覆盖该值。

自动分类器超时

当 Auto 模式处于启用状态时，分类器会有一个用于审查每批受控操作的时间预算。未在截止时间前完成审查的批次会以 classifier_unavailable 为由被拒绝；反复超时则会回退到手动审批 UI。默认值为 20 秒。

如果审查出现超时，首先应当尝试选择一个更快的分类器模型（参见 [models].auto_classifier）。如果你已经这样做了但仍然需要更多余量，可以提高截止时间：

[models]
auto_classifier_timeout = 60   # seconds; minimum 1, maximum 300

环境变量的优先级高于配置文件，而配置文件的优先级高于内置默认值。小于 1 或大于 300 的值会被钳制到下限或上限。非整数值会回退到默认值并给出警告。

Profile 覆盖（高级）

覆盖模型运行时 profile 中的字段，以改变 Deep Agents Code 解读模型能力的方式。可覆盖字段的完整列表参见 ModelProfile。最常见的用例是调低 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

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

使用 --profile-override 在 CLI 中覆盖 profile

若要在运行时覆盖模型 profile 字段而不编辑配置文件，可通过 --profile-override 传入一个 JSON 对象：

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

# Combine with --model
dcode --model google_genai:gemini-3.6-flash --profile-override '{"max_input_tokens": 4096}'

# In non-interactive mode
dcode -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'

这些值会叠加合并到配置文件的 profile 覆盖之上（CLI 优先）。优先级链为：模型默认值 < config.toml profile < CLI --profile-override。

--profile-override 的值会在会话中途的 /model 热切换之间保持——切换模型时会将该覆盖重新应用到新模型。

向交互式切换器添加模型

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

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

现在 /model 切换器会包含一个 Ollama 分区，其中列出这些模型。

这完全是可选的。你始终可以通过直接指定完整名称来切换到任意模型：

/model ollama:qwen3.6:27b

NOTE

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

自定义 base URL

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

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

关于兼容性信息和其他注意事项，请参阅你的服务商的参考文档。

兼容 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"]

NOTE

服务商在官方规范之上添加的任何功能都不会被纳入。如果该服务商提供了专门的 LangChain 集成包，请优先改用那个包。

WARNING

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

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

任意服务商

Deep Agents Code 可以与任何以 LangChain BaseChatModel 形式提供、且支持工具调用的 LLM 协同工作。内置服务商开箱即用；较为小众或自研的模型则需要多一些设置。将 class_path 指向它的 BaseChatModel 子类，Deep Agents Code 就会直接导入并实例化该类。

[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 令牌、专有请求头、mTLS 等）而非标准 API 密钥时，这一点很有用：

[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 切换到该模型。

NOTE

Deep Agents Code 要求支持工具调用。如果你的自定义模型支持工具调用，但 Deep Agents Code 并不知道这一点，请在服务商 profile 中声明它：

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

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 关键字参数传入：

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

WARNING

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

你的服务商包也可以选择在 <package>.data._profiles 中的 _PROFILES 字典里提供模型 profile，以代替在 models 键下定义它们。更多信息参见 LangChain 的模型 profile。

端点、密钥与网关

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 自身的默认端点，当以上各项都未设置时生效。

NOTE

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

与 API 密钥一样，DEEPAGENTS_CODE_ 前缀会将端点限定在 Deep Agents Code 的范围内，而不会影响其他工具。对于任何其他服务商，可用 base_url_env 声明变量名，端点会以相同的方式解析并配对：

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

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

[models.providers.myprovider]
base_url = "https://fixed.example/v1"   # used
base_url_env = "MYPROVIDER_BASE_URL"    # ignored while base_url is set

覆盖操作会保持配对关系

当你通过 /auth 保存密钥时，你所输入的端点（如果留空，则为服务商的默认端点）会与该密钥一起应用。以空白 base URL 保存密钥时，还会清除环境中已设置的任何端点（例如你的 shell 导出的网关 OPENAI_BASE_URL），这样你的密钥就会发往服务商的默认端点，而不是那个网关。

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

托管网关

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

若要改用你自己的密钥，可通过 /auth 保存它（将 base URL 留空以使用服务商默认值，或显式设置它），或者设置带 DEEPAGENTS_CODE_ 前缀的密钥和端点。这两种方式都会覆盖网关的那对值，并且不会留下不匹配的端点。

JS 解释器

[interpreter] 部分用于调节内置的 JavaScript 解释器（js_eval 工具），该解释器在 QuickJS 沙箱中运行智能体编写的代码。这些键仅适用于配置文件；--interpreter 和 --interpreter-tools 标志的等效用法参见命令行选项。

[interpreter]
enable_interpreter = true       # default
timeout_seconds = 5.0           # default
memory_limit_mb = 64            # default
max_ptc_calls = 256             # default
max_result_chars = 4000         # default
ptc = "safe"                    # default: "safe"
ptc_acknowledge_unsafe = false  # default

boolean默认 true

将 QuickJS REPL middleware（js_eval）接入主智能体（仅限本地会话）。设为 false 可完全禁用该解释器；可通过 --interpreter 为单个会话重新启用。

number默认 5.0

QuickJS REPL 每次调用的挂钟超时时间。

integer默认 64

QuickJS 的堆内存上限（以 MB 为单位），在整个会话中共享。

integer默认 256

每次 js_eval 调用中 tools.* 主机桥接调用的最大次数。

integer默认 4000

在截断之前，js_eval 结果与捕获的 stdout 所允许的字符数上限。

string | boolean | string[]默认 "safe"

针对 js_eval 的程序化工具调用允许列表。可接受的值：

• "safe"（默认）：只读预设集 read_file、glob、grep。这些工具在 REPL 之外不受审批控制，因此开放它们并不会带来审批绕过。网络工具、子智能体派发、shell 执行和文件写入被有意排除。
• "all"：所有主机工具。除非全局禁用了审批，否则需要 ptc_acknowledge_unsafe = true，因为 PTC 调用会绕过审批提示。
• 一个工具名称列表，例如 ["safe", "web_search"] —— 其中的 "safe" 条目会展开为该预设集。列表中不允许出现 "all"。
• false 或 []：REPL 中没有任何工具访问权限（纯解释器）。true 会被拒绝——请使用 "safe"、"all" 或显式的列表。

boolean默认 false

确认 ptc = "all" 会将所有工具暴露给那些绕过审批提示的 PTC 调用。除非在禁用审批的情况下运行，否则 ptc = "all" 必须设置此项。

Python 扩展

[extensions] 部分用于控制 Python 扩展的发现与项目信任。即使此处已启用扩展加载，实验性功能的开关仍然是必需的。

[extensions]
enabled = true
trust = "ask"
extra_paths = [
    "extensions/policy.py",
    "~/src/company-extensions",
]

boolean默认 true

为所有来源启用 Python 扩展发现，包括 -e / --extension 路径、用户与项目目录、插件以及入口点。设置 DEEPAGENTS_CODE_EXTENSIONS 可覆盖该值。这两项设置都要求在启动 Deep Agents Code 之前设置 DEEPAGENTS_CODE_EXPERIMENTAL=1。

string默认 "ask"

为 <project>/.deepagents/extensions/ 中的项目扩展设置默认策略：ask 在交互式启动时进行询问，always 直接加载它们，never 则跳过它们。设置 DEEPAGENTS_CODE_EXTENSIONS_TRUST 可覆盖该值。只有当你打开的每个项目都是可信的时，才应使用 always。

string[]默认 []

添加经用户授权的 Python 扩展文件或目录。相对路径从 Deep Agents Code 的 profile 目录开始解析；~ 会展开为你的主目录。

智能体运行时限制

LangGraph 的图步数预算是 dcode 智能体图在一轮对话中可执行的最大节点调用次数。可通过 [runtime] 部分配置该递归上限：

[runtime]
recursion_limit = 5000

Deep Agents Code 不设置默认值。当没有任何来源设置有效值时，将采用 LangGraph 服务端的默认值。来自托管配置、环境和 config.toml 的值必须是 25 到 100000（含）之间的整数。无效值会记录一条警告，然后继续向下一个来源解析。--recursion-limit 标志接受任何大于或等于 1 的整数。

优先级（由高到低）：

1. 管理员所有的 managed_config.toml
2. --recursion-limit CLI 标志
3. DEEPAGENTS_CODE_RECURSION_LIMIT 环境变量
4. config.toml 中的 [runtime].recursion_limit
5. LANGGRAPH_DEFAULT_RECURSION_LIMIT 环境变量
6. LangGraph 服务端默认值

使用 dcode config get runtime.recursion_limit 可查看 Deep Agents Code 实际生效的值及其来源。如果结果为空，则该上限由 LangGraph 服务端决定。

dcode --recursion-limit 5000

NOTE

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

另请参阅

• 配置
• 服务商凭据
• 服务商
• Python 扩展
• CLI 参考

---