Provider row labels

每一行显示提供商名称及其密钥来源：

该 /auth 提示还具有可选的 **基础 URL** 字段。留空以使用提供商的默认端点，或设置自定义端点与此密钥一起使用。基础 URL 与密钥一起保存。请参阅 端点、密钥和网关 以了解端点如何解析，包括与网关一起使用时的解析方式。

使用 ChatGPT 登录

选择 openai_codex 中的 /auth 提供商会启动浏览器登录而非提示输入 API 密钥，让您可以使用 ChatGPT 订阅使用 OpenAI 模型。如需重新认证或退出登录，请再次选择 openai_codex 。请参阅 使用 ChatGPT 登录（Codex 模型） 以了解完整流程。

/auth 管理 **LLM 提供商** 凭证和 **Tavily 网络搜索密钥**。在此输入的 Tavily 密钥会与您的提供商密钥一起存储，并在下次启动时激活网络搜索——请参阅 启用 Tavily 网络搜索。其他工具凭证如 LANGSMITH_API_KEY （tracing）会从环境变量读取—— 在以下位置设置 ~/.deepagents/.env 或你的 shell.

从 shell 管理凭证（dcode auth)

该 dcode auth 命令组是 /auth manager: it manages the same stored credentials without launching the TUI, which makes it usable for dotfile bootstrap, CI/CD, and setting a key on a remote box over SSH. The subcommands mirror the modal's verbs:

set 默认从 **stdin** 读取密钥，因此永远不会进入 shell 历史记录或 argv。通过管道输入密钥，或使用 --from-env VAR 从进程环境变量复制密钥：

# Pipe the key in (stdin)
echo "$ANTHROPIC_API_KEY" | dcode auth set anthropic

# Copy it from an existing environment variable
dcode auth set openai --from-env OPENAI_API_KEY

删除存储的密钥或打印存储位置：

dcode auth remove anthropic
dcode auth path

环境变量（CI 和无头模式）

For non-interactive runs, CI/CD pipelines, or anywhere a TUI isn't available, export the provider's env var in your shell:

# Prefix with DEEPAGENTS_CODE_ to scope a key to Deep Agents Code only,
# leaving a shared key used by other CI steps untouched

要改为将密钥保存在文件中，请在 .env 文件中定义它们.

密钥解析顺序

当某个 provider 的密钥在多个地方设置时，Deep Agents Code 使用第一个设置的：

1. **DEEPAGENTS_CODE_前缀的环境变量** — 例如 DEEPAGENTS_CODE_OPENAI_API_KEY 作为内联 shell 导出。The DEEPAGENTS_CODE_ 前缀 是明确的"在 Deep Agents Code 中使用此密钥"覆盖。
2. **应用存储的密钥** — 在 /auth 凭据管理器中输入。
3. **普通 provider 环境变量** — 例如 OPENAI_API_KEY，来自您的 shell 或 .env files.

应用存储的密钥会覆盖同一 provider 的普通环境变量密钥，但 DEEPAGENTS_CODE_前缀的密钥会覆盖应用存储的密钥。前缀是覆盖已存储密钥的简便方式，适用于单次运行，无需清除：

# With a key already stored via /auth, a plain env var does not override it.
# dcode still uses the app-stored key for this run:
OPENAI_API_KEY=sk-xxxx dcode -n "..."

# The DEEPAGENTS_CODE_ prefix does override it, for this run only:
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-xxxx dcode -n "..."

这种层级设计是为了处理常见情况：您的机器已经为其他目的导出了普通 provider 变量——一个共享的 OPENAI_API_KEY 被其他工具、脚本或 CI 使用——您不想让 Deep Agents Code 重用它。应用存储的密钥或 DEEPAGENTS_CODE_前缀的变量为 Deep Agents Code 提供其自己的值，同时保留不带前缀的变量供其他所有内容使用，因此两者不会混淆。

每个 provider 的 API 密钥及其端点（base_url）作为一对从同一来源解析。参见 端点、密钥和网关.

使用 Tavily 启用网络搜索

内置的 web_search 工具使用 Tavily。在您提供密钥之前，Deep Agents Code 启动时会显示"网络搜索已禁用"通知。您可以将密钥存储在 /auth 凭据管理器中，Tavily 作为非模型服务出现，或设置 TAVILY_API_KEY 环境变量。

        /auth
        

                TAVILY_API_KEY=tvly-...
                

环境变量

除了 shell 导出外，Deep Agents Code 还会从 dotenv 文件读取环境变量，这样您可以将 API 密钥保留在 shell 配置之外，避免在 .env 文件中跨项目重复。

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

加载顺序和优先级

启动时，Deep Agents Code 会读取最近的项目 .env，通过搜索您启动的目录并向上遍历其父目录来查找（第一个 .env 的胜出），然后 ~/.deepagents/.env 作为所有项目的全局后备。项目 .env 优先于全局配置，两者都不会覆盖 shell 中已设置的值。运行 /reload 会重新读取两者 .env 文件，这样您就可以在不重启的情况下更改键，shell 值仍然优先。这适用于 Deep Agents Code 读取的每个变量（例如 TAVILY_API_KEY 或 DEEPAGENTS_CODE_* 设置）。提供商 API 密钥有额外的解析规则；请参阅 提供商凭证.

DEEPAGENTS_CODE_ 前缀

所有 Deep Agents Code 特定的环境变量都使用 DEEPAGENTS_CODE_ 前缀（例如 DEEPAGENTS_CODE_AUTO_UPDATE, DEEPAGENTS_CODE_DEBUG）。请参阅 环境变量参考 获取完整列表。

此前缀还可用作 Deep Agents Code 读取的任何环境变量（包括第三方凭证）的覆盖机制。Deep Agents Code 首先检查 DEEPAGENTS_CODE_{NAME} ，然后回退到 {NAME}:

# Give Deep Agents Code its own value, without affecting other tools
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-cli-only

# Or set it empty so Deep Agents Code ignores a key exported in your shell
DEEPAGENTS_CODE_ANTHROPIC_API_KEY=

配置文件

~/.deepagents/config.toml 允许您自定义模型提供商、设置默认值以及向模型构造函数传递额外参数。本节涵盖：

• 默认值：固定一个 默认模型 or 代理.
• 提供商设置：[[models.providers.<name>] 表](#provider-configuration)， 构造函数参数, 重试, 配置文件覆盖和 将模型添加到 /model 切换器.
• 自定义端点和提供商: 自定义基础URL, OpenAI 或 Anthropic 兼容 API，以及 任意提供商.
• 端点和网关：如何 API密钥和基础URL如何协同解析，包括通过托管网关。

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

[models]
default = "ollama:qwen3:4b"             # your intentional long-term preference
recent = "google_genai:gemini-3.5-flash"   # last /model switch (written automatically)

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

默认代理和最近使用的代理

[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 会绕过两者，以便恢复线程的原始代理。参见 命令参考 了解相关标志。

提供商配置

每个提供商是 [models.providers]:

[models.providers.<name>]
display_name = "My Provider"
api_key_url = "https://provider.example/keys"
models = ["gpt-4o"]
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-4o"]
temperature = 0.7

下的一个 TOML 表。提供商具有以下配置选项：

要在交互式 /model 切换器中显示的模型名称列表，定义为 <name>的提供商。对于已内置模型配置文件的提供商，您在此处添加的名称会与内置名称一起显示（适用于尚未添加到包中的新发布模型）。对于 任意提供商，此列表是切换器中模型的唯一来源。

此处列出的模型 **会绕过** 任何应用的基于配置文件的 过滤条件，始终显示在切换器中。这是显示因配置文件中缺少 tool_calling 支持或尚不存在而被排除的模型的推荐方式。

此键是可选的。您始终可以直接将任何模型名称传递给 /model or --model ，无论其是否出现在切换器中；提供商会在请求时验证该名称。

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

大多数聊天模型包会自动从默认环境变量中读取。请参阅 提供商参考 表格以了解每个内置提供商会检查的变量名。对于不在该表格中的提供商，请设置 api_key_env 为其变量名（请参阅 任意提供商).

在授权界面中显示的人类可读提供商名称。当提供商的配置键针对机器优化时使用此项（例如， my_gateway），但其界面标签应包含空格或品牌大写。

用户创建或管理 API 密钥的提供商页面 URL。 /auth 模态框会在 API 密钥输入前链接到此页面。此值是 URL，不是凭证。

如果支持，覆盖提供商使用的基础 URL。请参阅提供商包的 参考文档 了解更多信息。

请参阅 兼容的 API 以将内置提供商指向兼容的端点，或 任意提供商 以获取通过 class_path.

保存此提供商基础 URL 的环境变量名称，类似于 api_key_env。请使用此选项而不是 base_url 当端点来自环境而非固定值时——例如因机器或 CI 作业而不同的网关 URL——这样可以更改而无需编辑 config.toml and can take part in endpoint resolution and key/endpoint pairing (see 端点、密钥和网关）。它还将其扩展到 内置集之外的提供商；请参阅 任意提供商.

如果两者都设置了，静态 base_url wins:

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

转发到模型构造函数的额外关键字参数。扁平键（例如， temperature = 0）适用于此提供商的每个模型。模型键控的子表（例如， [params."gpt-4o"]）仅覆盖该模型的个别值；合并是浅层的（冲突时模型优先）。

请勿放置凭证（例如， api_key) in params。请使用 api_key_env 指向环境变量。

（高级）覆盖模型运行时的字段 配置文件 (e.g., max_input_tokens）。扁平键适用于此提供商的每个模型。模型键控的子表（例如， [profile."claude-sonnet-4-5"]）仅覆盖该模型的个别值；合并是浅层的（冲突时模型优先）。这些覆盖在模型创建后应用，因此对上下文限制显示、自动摘要和任何其他读取配置文件的特性生效。请参阅 配置文件覆盖 了解示例和 --profile-override flag.

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

此提供商是否显示在 /model 选择器中。设置为 false 用于隐藏从已安装包自动发现的提供程序（例如，您不希望其干扰模型切换器的传递依赖项）。您仍然可以直接使用已禁用的提供程序，通过 /model provider:model or --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} — 无覆盖，仅使用提供程序级参数。

合并是浅层的：模型子表中存在的任何键都会替换提供程序级参数中的相同键，而仅存在于提供程序级别的键会被保留。

重试

使用顶级 [retries] 部分配置临时模型提供程序错误的重试次数。Deep Agents Code 将这些值传递给接受重试计数构造函数 kwargs 的提供程序集成。如果省略此部分，则应用提供程序 SDK 默认值。

[retries]
max_retries = 2

[retries.fireworks]
max_retries = 3

[retries.anthropic]
max_retries = 0

全局 [retries].max_retries 值适用于所有支持的提供程序。特定于提供程序的表（如 [retries.fireworks]）会覆盖该提供程序的全局值。值必须是大于或等于 0.

大多数支持的提供程序将重试次数作为 max_retries接收。某些集成使用不同的构造函数 kwarg。对于任意提供程序，或要覆盖已知提供程序的已注册 kwarg，请在提供程序特定的重试表中设置 param ：

[retries]
max_retries = 2

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

param 必须是有效的 Python 标识符字符串，如 "max_retries" or "retries"。Deep Agents Code 会忽略未设置 param的未知提供程序，因为传递错误的重试 kwarg 可能会破坏模型创建。

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

1. --max-retries N，在提供程序的已解析重试 kwarg 下应用
2. --model-params 与提供程序的重试 kwarg 一起使用，例如 '{"max_retries": N}' or '{"retries": N}'
3. [models.providers.<provider>.params] 与提供程序的重试 kwarg
4. [retries.<provider>].max_retries
5. [retries].max_retries
6. 提供程序 SDK 默认值

配置文件覆盖（高级）

覆盖模型运行时配置文件中的字段，以更改 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

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

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

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

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

向交互式切换器添加工具

某些提供商（例如 langchain-ollama）不捆绑模型配置文件数据（请参阅 提供商参考 获取完整列表）。在这种情况下，交互式 /model 切换器不会列出该提供商的模型。您可以通过在配置文件中为该提供商定义一个 models 列表来填补这个空白：

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

该 /model 切换器现在将包含一个Ollama部分，列出这些模型。

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

/model ollama:qwen3.6:27b

自定义基础URL

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

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

请参阅您的提供商的参考文档以获取兼容性信息和附加注意事项。

兼容的API

对于暴露与OpenAI或Anthropic有线兼容的API的提供商，您可以使用现有的 langchain-openai or langchain-anthropic 包，方法是让 base_url 指向提供商的端点：

[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"]

任意提供商

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 or --model xyz:abc-xyz-1.

因为 Deep Agents Code 在启动时导入 class_path 类，定义它的包必须能够从运行 dcode的同一环境中导入。内置提供程序作为 安装附加组件提供，但自定义或内部包不是其中之一。将其安装到 dcode 环境中，并使用 --package flag:

dcode --install my_package --package

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

当切换到 my_custom:my-model-v1 （通过 /model or --model），模型名称（my-model-v1）作为 model kwarg:

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

你的提供程序包可以选择在 _PROFILES 字典中提供模型配置 <package>.data._profiles ，而不是在 models 键下定义它们。请参阅 LangChain 模型配置 了解更多。

端点、密钥和网关

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

如何 base_url 解析

Deep Agents Code 按以下顺序解析提供程序的端点（首次匹配优先）：

1. **base_url in config.toml** 用于提供程序。
2. ** DEEPAGENTS_CODE_前缀的端点变量。**
3. **普通端点变量** 在环境中（例如， OPENAI_BASE_URL).
4. **使用保存的端点 /auth credential.** 此步骤将已保存的端点应用于没有端点变量的提供商（例如您在未声明的情况下添加的提供商） base_url_env。步骤 2-3 对于这些没有可读取的变量，因此直接使用已保存的端点。对于有端点变量的提供商，已保存的端点已在步骤 2 或 3 生效（它被写入该变量），因此此步骤不会改变任何内容。无论哪种方式，在 /auth applies.
5. **提供商 SDK 自身的默认端点**，当以上均未设置时。

与 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 存储密钥也会清除环境中已设置的任何端点（例如，网关 OPENAI_BASE_URL 由 shell 导出），因此您的密钥将发送到提供商的默认端点而不是该网关。

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, or GOOGLE_GEMINI_BASE_URL）。Deep Agents Code 默认使用该配对，因此无需配置。

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

技能目录白名单

默认情况下，当 Deep Agents Code 加载技能时会验证解析后的技能文件路径是否保持在标准 技能目录之一。这可以防止技能目录内的符号链接读取这些根目录之外的任意文件。

如果您将共享技能资产存储在非标准位置，并使用来自标准技能目录的符号链接来引用它们，可以将该位置添加到容器白名单中。这 **不会** 添加新的技能发现位置：技能仍然只能从标准目录中发现。

添加到技能容器白名单的路径。支持 ~ expansion.

    [skills]
    extra_allowed_dirs = [
        "~/shared-skills",
        "/opt/team-skills",
    ]
    

或者，设置 DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS 环境变量为冒号分隔的列表：

当设置环境变量时，它优先于配置文件值。更改在 /reload.

主题

使用 /theme 打开交互式主题选择器。在列表中导航以实时预览主题，按 Enter 将您的选择保存到 config.toml.

Deep Agents Code 附带许多内置主题。默认主题是 langchain，这是一个带有 LangChain 品牌色彩的深色主题。选定的主题保存在 [ui]:

[ui]
theme = "langchain-dark"

用户自定义主题

在以下位置定义自定义主题 [themes.<name>] 中的部分 config.toml。每个部分需要 label （字符串）。 dark （布尔值）默认为 false 如果省略则设为 true 用于深色主题。所有颜色字段都是可选的——省略的字段会根据以下内容回退到内置的深色或浅色调色板 dark flag.

[themes.my-solarized]
label = "My Solarized"
dark = true
primary = "#268BD2"
warning = "#B58900"

# Theme names with spaces require TOML quoting
[themes."ocean breeze"]
label = "Ocean Breeze"
primary = "#0077B6"
background = "#CAF0F8"

用户定义的主题与内置主题一起显示在 /theme selector.

覆盖内置主题颜色

要调整内置主题的颜色而不创建新主题，请使用 [themes.<builtin-name>] 部分。只读取颜色字段—— label 和 dark 从内置继承：

[themes.langchain]
primary = "#FF5500"

省略的颜色字段保留现有的内置值。

对 [themes.*] 部分的更改在以下情况下生效 /reload.

将主题映射到终端

如果在具有不同配色方案的终端之间切换（例如，深色的 iTerm 和浅色的 Apple Terminal），请将每个终端映射到以下位置的主题 [ui.terminal_themes]。Deep Agents Code 会匹配 shell 的 TERM_PROGRAM 并自动应用映射的主题：

[ui.terminal_themes]
"Apple_Terminal" = "langchain-light"
"iTerm.app" = "langchain"

按 T 在 /theme 选择器中保存当前终端的高亮主题，或运行 echo $TERM_PROGRAM 查找终端标识符并手动添加。

Auto-update

Deep Agents Code 默认自动检查并安装更新。

要选择退出自动更新：

        [update]
        auto_update = false
        

环境变量优先于配置文件。

启用时（默认），Deep Agents Code 会在会话开始时检查 PyPI 是否有新版本，并自动升级。禁用时，Deep Agents Code 会显示更新提示和相应的安装命令。

要完全禁止自动更新检查：

        [update]
        check = false
        

禁用更新检查也会阻止启动时的自动更新安装。

您仍可随时使用 /update 斜杠命令手动检查和安装更新，该命令会执行按需检查并内联报告成功或失败。

升级后，Deep Agents Code 会在下次启动时显示"新增功能"横幅，并附上更新日志链接。

会话退出时，如果在会话期间检测到新版本，则会显示更新横幅作为提醒。

卸载

要移除 dcode 和 deepagents-code 二进制文件以及隔离的工具环境，请运行：

uv tool uninstall deepagents-code

卸载命令不会移除用户配置或会话数据。Deep Agents Code 将这些文件存储在 ~/.deepagents/下，包括 config.toml, hooks.json、全局 .env和 .state/ 内容（如保存的会话和凭据）。要同时删除这些数据，请运行：

rm -rf ~/.deepagents

托管部署

安装脚本 支持以 root 身份运行，面向 macOS MDM 工具（Kandji、Jamf 等），这些工具在最小 root 环境中执行脚本。

当 id -u is 0时，脚本会：

1. 解析真实控制台用户的 HOME （通过 /dev/console or a /Users 目录扫描）
2. chown在每个安装步骤后将所有创建的文件的所有者更改回目标用户

非 root 安装不受影响：当不以 root 身份运行时，所有 root 特定代码路径都会短路跳过。

使用环境变量固定安装

安装脚本读取环境变量，允许您固定版本、选择额外组件并选择 Python 版本范围。在管道安装的同一行设置它们：

# Pin an exact version for reproducible installs across the fleet
curl -LsSf https://langch.in/dcode | DEEPAGENTS_CODE_VERSION="0.1.16" bash

要安装的确切包版本，例如 0.1.0 （或预发布版本，如 0.1.0rc1）。与 DEEPAGENTS_CODE_PRERELEASE 互斥——同时设置两者会报错，因为精确固定已经选择了单一版本。

解析最新版本时应用的 uv 预发布策略： disallow, allow, if-necessary, explicit, or if-necessary-or-explicit。与 DEEPAGENTS_CODE_VERSION.

逗号分隔的 pip 额外组件，例如 ollama, ollama,groq, or daytona。请参阅 pyproject.toml 了解可用的额外组件。

安装使用的 Python 版本。

设为 1 以跳过可选工具检查。

设为 1 以显示 uv 的原始 stderr（计时行、未过滤的包差异）以及默认静默的状态行（可选工具检查、安装后页脚）。调试安装时很有用。

uv 二进制文件的路径。如果未设置则自动检测。

托管安装默认启用自动更新。要退出，请设置 DEEPAGENTS_CODE_AUTO_UPDATE=0 在用户的 shell 配置文件中或部署 config.toml 使用 [update] auto_update = false to ~/.deepagents/config.toml。要完全禁止自动更新和更新检查，请设置 DEEPAGENTS_CODE_NO_UPDATE_CHECK=1 或部署 [update] check = false.

要将所有用户的模型流量通过托管网关路由（在整个舰队范围内配置网关密钥和基础 URL），请参阅 托管网关.

环境变量参考

所有 Deep Agents Code 特定的环境变量都使用 DEEPAGENTS_CODE_ 前缀。请参阅 DEEPAGENTS_CODE_ 前缀 了解前缀如何同时作为第三方凭据的覆盖机制。

切换自动 Deep Agents Code 更新。默认启用；设置为 0, false, no, or off 以选择退出。

启用详细的调试日志记录到文件。接受 1, true, yes, on （不区分大小写）表示启用； 0, false, no, off、空字符串或未设置表示禁用。启用后，每个会话的服务器日志文件在关闭时会被保留，其路径会打印到 stderr 以便排查。

调试日志文件的路径。

添加到 技能隔离白名单的冒号分隔路径.

覆盖 Deep Agents Code 自身代理追踪的 LangSmith 项目名称。Shell 命令仍使用用户的原始 LANGSMITH_PROJECT，因此应用、测试或脚本追踪可以出现在单独的项目中。请参阅 使用 LangSmith 进行追踪.

第二个 LangSmith 项目，用于 *也* 写入代理追踪。设置后且追踪处于活跃状态时，每次代理运行都会被双重写入主项目（默认来自 DEEPAGENTS_CODE_LANGSMITH_PROJECT, or deepagents-code ）和此项目。默认关闭。请参阅 将追踪双重写入第二个项目.

设置后禁用自动更新检查。这也会阻止启动时的自动更新安装。

允许的逗号分隔 shell 命令（或 recommended / all).

将用户标识符附加到 LangSmith 追踪元数据中。

外部编辑器

按 Ctrl+X 或输入 /editor 在外部编辑器中编写提示词。Deep Agents Code 会检查 $VISUAL，然后是 $EDITOR，然后回退到 vi (macOS/Linux) or notepad （Windows）。GUI 编辑器（VS Code、Cursor、Zed、Sublime Text、Windsurf）会自动接收一个 --wait 标志，以便 Deep Agents Code 在你关闭文件前保持阻塞。

# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)

钩子

钩子允许外部程序对 Deep Agents Code 生命周期事件做出反应。在 ~/.deepagents/hooks.json 中配置命令，每次事件触发时，它会将 JSON 负载输送到每个匹配命令的 stdin。

钩子在后台线程中以即发即忘的方式运行——它们永远不会阻塞 Deep Agents Code，失败会被记录而不会中断你的会话。

设置

创建 ~/.deepagents/hooks.json:

{
  "hooks": [
    {
      "command": ["bash", "-c", "cat >> ~/deepagents-events.log"],
      "events": ["session.start", "session.end"]
    }
  ]
}

现在每次会话启动或结束时，Deep Agents Code 都会将事件负载附加到 ~/deepagents-events.log.

钩子配置

配置文件包含一个单独的 hooks 数组。每个条目包含：

要运行的命令和参数。无 shell 展开：如需要请使用 ["bash", "-c", "..."] 。

要订阅的事件名称。省略或留空则接收 **所有** events.

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "task.complete"]
    },
    {
      "command": ["bash", "log_everything.sh"]
    }
  ]
}

上面的第二个 hook 没有 events 过滤器，因此它会接收 Deep Agents Code 发出的每个事件。

负载格式

每个 hook 命令通过 stdin 接收一个 JSON 对象，包含 "event" 键以及事件特定的字段：

{
  "event": "session.start",
  "thread_id": "abc123"
}

事件参考

session.start

当智能体会话开始时触发（交互和非交互模式）。

会话线程标识符。

session.end

当会话退出时触发。

会话线程标识符。

user.prompt

在交互模式下用户提交聊天消息时触发。

无其他字段。

input.required

当智能体需要人工输入时触发（人工介入中断）。

无其他字段。

permission.request

当一个或多个工具调用需要用户授权时，在批准对话框之前触发。

请求授权的工具名称。

tool.error

当工具调用返回错误时触发。

出错的工具名称。

task.complete

当智能体完成当前任务时触发（流式循环结束，无进一步中断）。

会话线程标识符。

context.compact

在 Deep Agents Code 压缩（汇总）对话上下文之前触发。

无其他字段。

执行模型

• 后台线程：Hook 子进程通过线程运行 asyncio.to_thread ，因此主事件循环永不被阻塞。
• 并发调度：当多个 hook 匹配一个事件时，它们在线程池中并发运行。
• 5 秒超时：每个命令有 5 秒超时。超过此时间的命令会被终止。
• Fire-and-forget: Errors are caught per-hook and logged at debug/warning level. A failing hook never crashes or stalls Deep Agents Code.
• 延迟加载：配置文件在首次事件调度时读取一次，并在会话剩余时间内缓存。
• 无 shell 展开：命令直接执行（不通过 shell）。如需 shell 功能（如管道或变量展开），请使用 ["bash", "-c", "..."] 包装。

Hook 示例

{
  "hooks": [
    {
      "command": ["bash", "-c", "jq -c . >> ~/.deepagents/hook-events.jsonl"],
      "events": []
    }
  ]
}

{
  "hooks": [
    {
      "command": [
        "bash", "-c",
        "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents\"'"
      ],
      "events": ["task.complete"]
    }
  ]
}

payload = json.load(sys.stdin)
event = payload["event"]

if event == "session.start":
    print(f"Session started: {payload['thread_id']}", file=sys.stderr)
elif event == "permission.request":
    print(f"Approval needed for: {payload['tool_names']}", file=sys.stderr)

{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "permission.request"]
    }
  ]
}

安全注意事项

Hooks 遵循与 Git hooks 或 shell 别名相同的信任模型——任何能写入 ~/.deepagents/hooks.json 的用户都能执行任意命令。这是设计使然：

• 无命令注入：负载数据仅作为 JSON 通过 stdin 传递，永不传递到命令行参数。 json.dumps 处理转义。
• 默认无 shell: 使用运行的命令 shell=False，防止 shell 注入。
• 格式错误的配置：无效的 JSON 或意外类型会产生日志警告，而非安全问题。