配置 - Docs by LangChain中文

Deep Agents Code 将配置存储在 ~/.deepagents/ 目录中。主要配置文件包括：

文件	格式	用途
`config.toml`	TOML	Model defaults、provider settings、constructor params、profile overrides、themes、update settings
`.env`	Dotenv	Global API keys、secrets 和其他 environment variables
`hooks.json`	JSON	External tool 订阅 Deep Agents Code lifecycle events
`.mcp.json`	JSON	Global MCP server definitions

~/.deepagents/.state/ 下的文件保存每台机器的 Deep Agents Code state，并自动管理。

Provider credentials

Deep Agents Code 需要为你使用的每个 model provider 配置 API key。推荐通过 /auth credential manager 添加。对于 non-interactive runs，请改为设置 environment variables。如果同一个 key 在多个位置设置，请参阅 Key resolution order 了解哪个值生效。

使用 `/auth`（推荐）

从任意 session 打开 credential manager：

/auth

该 manager 会列出当前安装中可用的 LLM providers，并标记已设置 key 的 providers。选择 provider 以添加或替换 key，也可以移除已存储的 key。你在此保存的 keys 会跨 sessions 保留。

Provider row labels

每一行都会显示 provider name，并附带其 key 的来源：

Label	含义
`[stored]`	通过 `/auth` 保存在此 manager 中的 key
`[env: VARNAME]`	Key 来自 environment variable `VARNAME`（解析后的名称，例如 `DEEPAGENTS_CODE_OPENAI_API_KEY` 或 `OPENAI_API_KEY`）
`[missing]`	未存储 key，且 env var 未设置；选择该行即可粘贴 key

/auth prompt 还包含可选的 base URL field。留空则使用 provider 的默认 endpoint；也可以设置与此 key 一起使用的自定义 endpoint。Base URL 会随 key 一起保存。关于 endpoints 如何解析，包括 gateways 场景，请参阅 Endpoints, keys, and gateways。

已存储的 base URL 不是 secret，可能会被记录到日志中；与其配对的 key 永远不会被记录。

Keys 的作用域限定于此机器上的你的用户账号，Deep Agents Code 不会将它们发送到配置的 provider API 之外的任何位置。

/auth 只管理 LLM provider credentials。TAVILY_API_KEY（web search）和 LANGSMITH_API_KEY（tracing）等 tool credentials 会改为从 environment 读取，请在 ~/.deepagents/.env 或 shell 中设置它们。

Environment variables（CI 和 headless）

对于 non-interactive runs、CI/CD pipelines，或任何无法使用 TUI 的环境，请在 shell 中 export provider 的 env var：

export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."

# Prefix with DEEPAGENTS_CODE_ to scope a key to Deep Agents Code only,
# leaving a shared key used by other CI steps untouched
export DEEPAGENTS_CODE_OPENAI_API_KEY="sk-..."

若要改为将 keys 保存在文件中，请在 .env file 中定义它们。

Key resolution order

当某个 provider 的 key 在多个位置设置时，Deep Agents Code 使用以下列表中第一个已设置的值：

带 DEEPAGENTS_CODE_ 前缀的 env var：例如以内联 shell export 形式设置的 DEEPAGENTS_CODE_OPENAI_API_KEY。DEEPAGENTS_CODE_ prefix 是显式的“在 Deep Agents Code 中使用此 key” override。
App-stored key：在 /auth credential manager 中输入的 key。
普通 provider env var：例如来自 shell 或 .env files 的 OPENAI_API_KEY。

对于同一 provider，app-stored key 优先于普通 env-var key，但带 DEEPAGENTS_CODE_ 前缀的 key 优先于 app-stored key。该 prefix 可在不清除已存储 key 的情况下，为单次 run 覆盖它：

# 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 "..."

这种分层适用于一种常见场景：你的机器已经为其他用途 export 了普通 provider variable，例如供其他 tools、scripts 或 CI 使用的共享 OPENAI_API_KEY，但你不希望 Deep Agents Code 复用它。App-stored key 或带 DEEPAGENTS_CODE_ 前缀的 variable 可以让 Deep Agents Code 使用自己的值，同时保留未加前缀的值供其他场景使用，二者不会混用。每个 provider 的 API key 及其 endpoint（base_url）会作为一对从同一来源解析。请参阅 Endpoints, keys, and gateways。

使用 Tavily 启用 web search

内置 web_search tool 使用 Tavily。在你提供 key 之前，Deep Agents Code 启动时会显示 “Web search disabled — TAVILY_API_KEY is not set” 通知。与 model provider keys 不同，Tavily 不由 /auth 管理，而是直接从 environment 读取。

获取 key

在 tavily.com 注册并复制 key（以 tvly- 开头）。Free tier 足以满足大多数 Deep Agents Code 使用场景。

添加到 environment

将 key 添加到 ~/.deepagents/.env，让每个 session 都能读取：

~/.deepagents/.env

TAVILY_API_KEY=tvly-...

或者在 shell 中 export，用于一次性 session：

export TAVILY_API_KEY=tvly-...

Shell exports 优先于 .env values（请参阅 Loading order and precedence）。若要将 key 的作用域限定到 Deep Agents Code，而不影响其他读取 TAVILY_API_KEY 的 tools，请使用 DEEPAGENTS_CODE_ prefix：DEEPAGENTS_CODE_TAVILY_API_KEY=tvly-...。

Reload 或 restart

在现有 session 中运行 /reload 以重新读取 .env files。下次启动时，“Web search disabled” 通知会消失，agent 可以调用 web_search。

Environment variables

除 shell exports 外，Deep Agents Code 还会从 dotenv files 读取 environment variables，因此你可以不把 API keys 放入 shell profile，并避免在多个项目中重复 .env files。

~/.deepagents/.env

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

Loading order and precedence

启动时，Deep Agents Code 会先读取最近的 project .env：它从启动目录开始搜索，并向上遍历父目录（找到的第一个 .env 生效），然后读取 ~/.deepagents/.env 作为所有项目的 global fallback。Project .env 优先于 global .env，但二者都不会覆盖 shell 中已设置的值。运行 /reload 会重新读取这两个 .env files，因此你可以在不重启的情况下更改 keys，同时 shell values 仍然优先。此规则适用于 Deep Agents Code 读取的每个 variable（例如 TAVILY_API_KEY 或 DEEPAGENTS_CODE_* settings）。Provider API keys 还有额外解析规则，请参阅 Provider credentials。

`DEEPAGENTS_CODE_` prefix

所有 Deep Agents Code-specific environment variables 都使用 DEEPAGENTS_CODE_ prefix（例如 DEEPAGENTS_CODE_AUTO_UPDATE、DEEPAGENTS_CODE_DEBUG）。完整列表请参阅 environment variable reference。对于 Deep Agents Code 读取的任何 environment variable（包括 third-party credentials），该 prefix 也可以作为 override 机制。Deep Agents Code 会先检查 DEEPAGENTS_CODE_{NAME}，再回退到 {NAME}：

~/.deepagents/.env

# 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=

Config file

~/.deepagents/config.toml 允许你自定义 model providers、设置 defaults，并向 model constructors 传递额外 parameters。本节涵盖：

Defaults：固定 default model 或 agent。
Provider setup：[models.providers.<name>] table、constructor params、profile overrides，以及向 /model switcher 添加 models。
Custom endpoints and providers：custom base URLs、OpenAI- or Anthropic-compatible APIs，以及 arbitrary providers。
Endpoints and gateways：API keys 和 base URLs 如何一起解析，包括通过 managed gateway 的场景。

Default 和 recent model

[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 command 只写入 [models].recent，因此你配置的 default 不会被 session 中途的 switches 覆盖。若要移除 default，请使用 /model --default --clear，或从 config file 中删除 default key。

Default 和 recent agent

[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 picker 中用 Enter 选择 agent 会写入 recent；在高亮行上按 Ctrl+S 会将其固定为 default。在同一行再次按 Ctrl+S 会清除 default。显式传入的 -a/--agent 始终覆盖二者，而 -r/--resume 会绕过二者，以恢复 thread 的原始 agent。相关 flags 请参阅 Command reference。

Provider configuration

每个 provider 都是 [models.providers] 下的一个 TOML table：

[models.providers.<name>]
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

Providers 支持以下配置选项：

models

string[]

optional

在 interactive /model switcher 中为 <name> 定义的 provider 显示的 model names 列表。对于已随包提供 model profiles 的 providers，你在这里添加的任何 names 都会额外显示在 bundled ones 之外（适用于尚未添加到 package 的新发布 models）。对于 arbitrary providers，此列表是 switcher 中 models 的唯一来源。此处列出的 models 会绕过任何基于 profile 的 filtering criteria，始终出现在 switcher 中。因此，对于因 profile 缺少 tool_calling 支持或尚不存在而被排除的 models，推荐用这种方式显示。此 key 是可选的。无论 model name 是否出现在 switcher 中，你都可以直接传给 /model 或 --model；provider 会在 request time 验证该 name。

api_key_env

string

optional

保存 API key 的 environment variable 名称（例如 "OPENAI_API_KEY"）。Deep Agents Code 会在启动时从该 env var 读取 credential，在创建 model 前验证访问权限。大多数 chat model packages 会自动从默认 env var 读取。每个 built-in provider 会检查哪个 variable name，请参阅 Provider reference table。对于不在该表中的 provider，请将 api_key_env 设置为其 variable name（请参阅 Arbitrary providers）。

base_url

string

optional

如果 provider 支持，则覆盖其使用的 base URL。更多信息请参阅 provider packages 的 reference docs。若要将 built-in provider 指向 wire-compatible endpoint，请参阅 Compatible APIs；若要配置通过 class_path 使用的 provider，请参阅 Arbitrary providers。

base_url_env

string

optional

保存此 provider base URL 的 environment variable 名称，与 api_key_env 对应。当 endpoint 来自 environment 而非固定值时，请使用此项而不是 base_url，例如因机器或 CI job 不同而变化的 gateway URL。这样无需编辑 config.toml 即可更改 endpoint，并且它可以参与 endpoint resolution 和 key/endpoint pairing（请参阅 Endpoints, keys, and gateways）。它也将这些机制扩展到 built-in set 之外的 providers；请参阅 Arbitrary providers。如果二者都设置，静态 base_url 优先：

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

params

object

optional

转发给 model constructor 的额外 keyword arguments。Flat keys（例如 temperature = 0）适用于此 provider 的每个 model。Model-keyed sub-tables（例如 [params."gpt-4o"]）只覆盖该 model 的单个值；merge 是浅层的（冲突时 model 胜出）。不要将 credentials（例如 api_key）放入 params。请改用 api_key_env 指向 environment variable。

profile

object

optional

（高级）覆盖 model runtime profile 中的 fields（例如 max_input_tokens）。Flat keys 适用于此 provider 的每个 model。Model-keyed sub-tables（例如 [profile."claude-sonnet-4-5"]）只覆盖该 model 的单个值；merge 是浅层的（冲突时 model 胜出）。这些 overrides 会在 model 创建后应用，因此会影响 context-limit display、auto-summarization，以及读取 profile 的任何其他 feature。示例和 --profile-override flag 请参阅 Profile overrides。

class_path

string

optional

用于 arbitrary model providers。格式为 module.path:ClassName 的 fully-qualified Python class。设置后，Deep Agents Code 会为 provider <name> 直接 import 并实例化此 class。该 class 必须是 BaseChatModel subclass。

enabled

boolean

default:"true"

optional

此 provider 是否出现在 /model selector 中。设置为 false 可隐藏从已安装 package 自动发现的 provider（例如你不希望占据 model switcher 的 transitive dependency）。你仍然可以通过 /model provider:model 或 --model 直接使用 disabled provider。

Model constructor params

params field 会将额外 arguments 转发给 model constructor。若要为某个 model 提供不同的值，请添加 model-keyed sub-table，这样无需复制整个 provider config：

[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}，model overrides 胜出。
ollama:llama3 获得 {temperature: 0, num_ctx: 8192}，没有 override，只使用 provider-level params。

Merge 是浅层的：model sub-table 中存在的任何 key 都会替换 provider-level params 中的同名 key，而仅存在于 provider level 的 keys 会保留。

若要进行一次性调整而不编辑 config.toml，请在启动时通过 --model-params 传入 JSON object，或在 session 中通过 /model 传入。CLI flags 优先级高于 config file。语法和 provider-specific examples 请参阅 providers 页面上的 Model parameters。

Profile overrides（高级）

覆盖 model runtime profile 中的 fields，以更改 Deep Agents Code 解读 model capabilities 的方式。可覆盖 fields 的完整列表请参阅 ModelProfile。最常见的用例是降低 max_input_tokens，以便更早触发 auto-summarization。这对测试或限制 context usage 很有用：

# Apply to all models from this provider
[models.providers.anthropic.profile]
max_input_tokens = 4096

Per-model sub-tables 的工作方式与 params 相同，冲突时 model-level value 胜出：

[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 overrides 会在创建后 merge 到 model profile 中。任何读取 profile 的 feature，例如 status bar 中的 context-limit display、auto-summarization thresholds、capability checks，都会看到覆盖后的 values。

CLI profile overrides with --profile-override

若要在 runtime 覆盖 model profile fields 而不编辑 config file，请通过 --profile-override 传入 JSON object：

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}'

这些值会 merge 到 config file profile overrides 之上（CLI 胜出）。优先级链为：model default < config.toml profile < CLI --profile-override。--profile-override values 会在 session 中途 /model hot-swaps 后继续保留，切换 models 会将 override 重新应用到新 model。

向 interactive switcher 添加 models

某些 providers（例如 langchain-ollama）不内置 model profile data（完整列表请参阅 Provider reference）。出现这种情况时，interactive /model switcher 不会列出该 provider 的 models。你可以在 config file 中为该 provider 定义 models list 来补齐：

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

/model switcher 现在会包含 Ollama section，并列出这些 models。这完全是可选的。你始终可以直接指定完整名称来切换到任意 model：

/model ollama:qwen3.6:27b

安装 langchain-ollama 且 daemon 可访问时，Deep Agents Code 会自动发现本地 pulled models，并将其 merge 到 switcher 中，无需 models list。Pull 新 models 后运行 /reload 刷新，或设置 DEEPAGENTS_CODE_OLLAMA_DISCOVERY=0 退出此行为。

Custom base URL

某些 provider packages 接受 base_url 来覆盖默认 endpoint。例如，langchain-ollama 通过底层 ollama client 默认使用 http://localhost:11434。若要指向其他位置，请在配置中设置 base_url：

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

兼容性信息和其他注意事项请参阅 provider 的 reference documentation。

Compatible APIs

对于暴露 OpenAI 或 Anthropic wire-compatible APIs 的 providers，你可以将 base_url 指向 provider endpoint，从而使用现有 langchain-openai 或 langchain-anthropic packages：

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

Provider 在 official spec 之上添加的任何 features 都不会被捕获。如果 provider 提供专用 LangChain integration package，请优先使用。

OpenAI provider 默认使用 Responses API，而大多数 OpenAI-compatible gateways 未实现该 API。如果你的 provider 仅支持 Chat Completions API，调用很可能失败。请显式禁用 Responses API：

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

Arbitrary providers

Deep Agents Code 可与任何作为 LangChain BaseChatModel 提供的 tool calling LLM 配合使用。Built-in providers 开箱可用；不常见或内部 model 需要稍作配置。将 class_path 指向它的 BaseChatModel subclass，Deep Agents Code 会直接 import 并实例化该 class。

[models.providers.my_custom]
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 是可选的。若要从 environment variable 读取 endpoint，而不是硬编码 base_url，请使用 base_url_env；之后它会像 built-in providers 一样解析并与 key 配对（请参阅 Endpoints, keys, and gateways）。 class_path providers 应在内部处理自己的 authentication。当你的 model 使用 custom auth（JWT tokens、proprietary headers、mTLS 等）而非标准 API key 时，这很有用：

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

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

使用此 config 后，通过 /model xyz:abc-xyz-1 或 --model xyz:abc-xyz-1 切换到该 model。

Deep Agents Code 需要 tool calling 支持。如果你的 custom model 支持 tool calling，但 Deep Agents Code 不知道，请在 provider profile 中声明：

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

虽然可选，但强烈建议将 max_input_tokens 设置为 model 的 context window。没有它，Deep Agents Code 无法显示 context 已使用多少，auto-summarization 也会回退到固定触发点（约 170,000 tokens），而不是基于 model window 的比例。对于 window 较小的 model，summarization 可能在达到 model hard limit 前不会运行，因此 conversation 变长后 requests 会开始失败。

由于 Deep Agents Code 会在启动时 import class_path class，定义该 class 的 package 必须能从运行 dcode 的同一 environment 中 import。Built-in providers 作为 install extras 提供，但 custom 或 in-house package 并不是。请使用 --package flag 将其安装到 dcode environment 中：

dcode --install my_package --package

在 session 中，运行 /install my_package --package --force。两种方式都会将 package 与 dcode 一起安装。如果 package 缺失或无法 import，Deep Agents Code 会跳过该 provider，其 models 不会出现在 /model 中。当你切换到 my_custom:my-model-v1（通过 /model 或 --model）时，model name（my-model-v1）会作为 model kwarg 传入：

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

class_path 会执行 config file 中的任意 Python code。它的 trust model 与 pyproject.toml build scripts 相同，你需要自行控制自己的机器。

你的 provider package 可以选择在 <package>.data._profiles 中提供 _PROFILES dict，以替代在 models key 下定义它们。更多信息请参阅 LangChain model profiles。

Endpoints、keys 和 gateways

API key 与其发送到的 endpoint 必须匹配：endpoint 必须接受该 key，否则 request 很可能失败。Deep Agents Code 会一起解析 key 和 endpoint，因此覆盖其中一个会同步更新另一个以保持匹配。例如，如果你用自己的 key 替换 gateway-provisioned key，Deep Agents Code 也会丢弃 gateway endpoint，因此你的 key 会直接发送到 provider，而不是发送到会拒绝它的 gateway。

`base_url` 如何解析

Deep Agents Code 按以下顺序解析 provider endpoint（第一个匹配项胜出）：

Provider 在 config.toml 中的 base_url。
带 DEEPAGENTS_CODE_ 前缀的 endpoint variable。
Environment 中的普通 endpoint variable（例如 OPENAI_BASE_URL）。
随 /auth credential 保存的 endpoint。 此步骤会为没有 endpoint variable 的 provider 应用已保存 endpoint，例如你添加 provider 时没有声明 base_url_env。对于这些 provider，步骤 2-3 没有 variable 可读，因此会在此处直接使用已保存 endpoint。对于确实有 endpoint variable 的 provider，已保存 endpoint 已在步骤 2 或 3 生效（它会写入该 variable），因此此步骤不会更改任何内容。无论哪种情况，在 /auth 中输入的 endpoint 都会生效。
以上都未设置时，使用 provider SDK 自身的 default endpoint。

解析后的 endpoints 会作为 base_url constructor argument 传递给 model。

与 API keys 一样，DEEPAGENTS_CODE_ prefix 会将 endpoint 的作用域限定到 Deep Agents Code，而不影响其他 tools。对于任何其他 provider，请使用 base_url_env 声明名称，endpoint 会以相同方式解析并配对：

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

Literal 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

Overrides 会保持 key 和 endpoint 配对

当你使用 /auth 存储 key 时，输入的 endpoint（或留空时使用的 provider default）会与 key 一起应用。使用空白 base URL 存储 key 还会清除 environment 中已设置的任何 endpoint（例如 shell export 的 gateway OPENAI_BASE_URL），因此你的 key 会发送到 provider 的 default endpoint，而不是该 gateway。

Scope both the key and the endpoint to Deep Agents Code

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

Managed gateways

在配置了 model gateway 的机器上（例如 LangSmith gateway），gateway 通常会同时 export gateway key 和匹配的 endpoint variable（OPENAI_BASE_URL、ANTHROPIC_BASE_URL 或 GOOGLE_GEMINI_BASE_URL）。Deep Agents Code 默认使用这对值，因此无需配置。若要改用自己的 key，请通过 /auth 存储它（将 base URL 留空以使用 provider default，或显式设置），或者设置带 DEEPAGENTS_CODE_ 前缀的 key 和 endpoint。两种方式都会覆盖 gateway pair，并且不会留下不匹配的 endpoint。

Skill directory allowlist

默认情况下，Deep Agents Code 加载 skills 时会验证解析后的 skill file path 仍位于标准 skill directories 之一中。这可以防止 skill directories 内的 symlinks 读取这些 roots 之外的任意 files。如果你将 shared skill assets 存储在非标准位置，并使用来自标准 skill directory 的 symlinks 引用它们，可以将该位置添加到 containment allowlist。这不会添加新的 skill discovery location：skills 仍然只会从标准 directories 中发现。

extra_allowed_dirs

string[]

optional

添加到 skill containment allowlist 的 paths。支持 ~ expansion。

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

或者，将 DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS environment variable 设置为 colon-separated list：

export DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS="~/shared-skills:/opt/team-skills"

设置 environment variable 后，它优先于 config file value。更改会在 /reload 时生效。

Themes

使用 /theme 打开 interactive theme selector。浏览列表可实时 preview themes，按 Enter 将选择保存到 config.toml。 Deep Agents Code 内置许多 themes。Default theme 是 langchain，这是带有 LangChain brand colors 的 dark theme。选中的 theme 会保存到 [ui] 下：

[ui]
theme = "langchain-dark"

User-defined themes

在 config.toml 的 [themes.<name>] sections 下定义 custom themes。每个 section 都需要 label（str）。如果省略，dark（bool）默认为 false，对于 dark themes 请设置为 true。所有 color fields 都是可选的，省略的 fields 会根据 dark flag 回退到内置 dark 或 light palette。

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

User-defined themes 会与 built-in themes 一起出现在 /theme selector 中。

覆盖 built-in theme colors

若要调整 built-in theme 的 colors 而不创建新 theme，请使用 [themes.<builtin-name>] section。只会读取 color fields，label 和 dark 会从 built-in theme 继承：

[themes.langchain]
primary = "#FF5500"

省略的 color fields 会保留现有 built-in values。对 [themes.*] sections 的更改会在 /reload 时生效。

将 themes 映射到 terminals

如果你会在不同 color schemes 的 terminals 之间切换（例如 dark iTerm 和 light Apple Terminal），请在 [ui.terminal_themes] 下将每个 terminal 映射到一个 theme。Deep Agents Code 会匹配 shell 的 TERM_PROGRAM 并自动应用映射的 theme：

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

在 /theme picker 中按 T，即可为当前 terminal 保存高亮 theme；也可以运行 echo $TERM_PROGRAM 找到 terminal identifier 并手动添加。

Advanced: picker shortcuts, resolution order, terminal identifiers

Picker shortcuts

在 /theme selector 中：

N 在 display labels 和 canonical registry keys 之间切换，后者是 [ui] theme 和 [ui.terminal_themes] 接受的 keys。
T 将高亮 theme 保存到当前 TERM_PROGRAM 的 [ui.terminal_themes] 中。映射的 theme 会在 picker 中带有 (default) badge。

Common `TERM_PROGRAM` values

Keys 会与 environment variable 按原样匹配。如果包含 dots 或 special characters，请在 TOML 中加引号。

Terminal	`TERM_PROGRAM`
Apple Terminal	`Apple_Terminal`
iTerm2	`iTerm.app`
WezTerm	`WezTerm`
VS Code integrated terminal	`vscode`
Ghostty	`ghostty`

Resolution order

Deep Agents Code 每次启动时按以下优先级解析 theme：

DEEPAGENTS_CODE_THEME environment variable（显式 override）。
当前 TERM_PROGRAM 的 [ui.terminal_themes] mapping。
[ui] theme saved preference（由 /theme 设置）。
Built-in default（langchain）。

Auto-update

Deep Agents Code 可以自动检查并安装 updates。

Config file
Environment variable

[update]
auto_update = true

export DEEPAGENTS_CODE_AUTO_UPDATE=1

Environment variable 优先于 config file。启用后，Deep Agents Code 会在 session 开始时检查 PyPI 是否有新版本，并使用检测到的 install method（uv、Homebrew 或 pip）自动升级。禁用时（默认），Deep Agents Code 会显示带有适当 install command 的 update hint。你也可以随时使用 /update slash command 手动检查并安装 updates。该 command 会绕过 cache，并以内联方式报告成功或失败。升级后，Deep Agents Code 会在下次启动时显示 “what’s new” banner，并附带 changelog 链接。 Session 退出时，如果在 session 中检测到新版本，会显示 update banner 作为提醒。

Uninstall

若要移除 dcode 和 deepagents-code binaries 以及 isolated tool environment，请运行：

uv tool uninstall deepagents-code

Uninstall command 不会移除 user configuration 或 session data。Deep Agents Code 会将这些 files 存储在 ~/.deepagents/ 下，包括 config.toml、hooks.json、global .env，以及 .state/ 中保存的 sessions 和 credentials 等内容。若也要删除这些数据，请运行：

rm -rf ~/.deepagents

Managed deployments

Install script 支持以 root 身份运行，面向在 minimal root environment 中执行 scripts 的 macOS MDM tools（Kandji、Jamf 等）。当 id -u 为 0 时，script 会：

解析真实 console user 的 HOME（通过 /dev/console 或扫描 /Users directory）
在每个 install step 后，将所有创建的 files chown 回 target user

Non-root installs 不受影响：未以 root 运行时，所有 root-specific code paths 都会短路。若要为 managed installs 预配置 auto-update，请在 user 的 shell profile 中设置 DEEPAGENTS_CODE_AUTO_UPDATE=1，或将包含 [update] auto_update = true 的 config.toml 部署到 ~/.deepagents/config.toml。若要完全抑制 automatic updates 和 update checks，请设置 DEEPAGENTS_CODE_NO_UPDATE_CHECK=1。若要通过 managed gateway 路由每个 user 的 model traffic（fleet-wide 配置 gateway key 和 base URL），请参阅 Managed gateways。

Environment variable reference

所有 Deep Agents Code-specific environment variables 都使用 DEEPAGENTS_CODE_ prefix。关于该 prefix 如何作为 third-party credentials 的 override 使用，请参阅 DEEPAGENTS_CODE_ prefix。

DEEPAGENTS_CODE_AUTO_UPDATE

string

optional

启用 automatic Deep Agents Code updates（1、true 或 yes）。

DEEPAGENTS_CODE_DEBUG

string

optional

启用 verbose debug logging 到文件。接受 1、true、yes、on（不区分大小写）作为启用；0、false、no、off、空字符串或未设置表示禁用。启用后，per-session server log file 会在 shutdown 时保留，其 path 会打印到 stderr 以便 triage。

DEEPAGENTS_CODE_DEBUG_FILE

string

default:"/tmp/deepagents_debug.log"

optional

Debug log file 的 path。

DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS

string

optional

添加到 skill containment allowlist 的 colon-separated paths。

DEEPAGENTS_CODE_LANGSMITH_PROJECT

string

optional

覆盖 agent traces 的 LangSmith project name。请参阅 Trace with LangSmith。

DEEPAGENTS_CODE_NO_UPDATE_CHECK

string

optional

设置后禁用 automatic update checking。

DEEPAGENTS_CODE_SHELL_ALLOW_LIST

string

optional

允许的 comma-separated shell commands（或 recommended / all）。

DEEPAGENTS_CODE_USER_ID

string

optional

将 user identifier 附加到 LangSmith trace metadata。

External editor

按 Ctrl+X 或输入 /editor，即可在 external editor 中编写 prompts。Deep Agents Code 会先检查 $VISUAL，再检查 $EDITOR，最后回退到 vi（macOS/Linux）或 notepad（Windows）。GUI editors（VS Code、Cursor、Zed、Sublime Text、Windsurf）会自动接收 --wait flag，因此 Deep Agents Code 会阻塞，直到你关闭文件。

# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)
export VISUAL="code"    # GUI editor (--wait auto-injected)
export EDITOR="nvim"    # Terminal fallback

Hooks

Hooks 允许 external programs 响应 Deep Agents Code lifecycle events。在 ~/.deepagents/hooks.json 中配置 commands 后，每当 event 触发，Deep Agents Code 都会将 JSON payload pipe 到每个匹配 command 的 stdin。 Hooks 会在 background thread 中以 fire-and-forget 方式运行。它们不会阻塞 Deep Agents Code，失败会被记录到日志中，且不会中断你的 session。

设置

创建 ~/.deepagents/hooks.json：

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

现在每当 session 开始或结束，Deep Agents Code 都会将 event payload 追加到 ~/deepagents-events.log。

Hook configuration

Config file 包含单个 hooks array。每个 entry 包含：

command

list[str]

required

要运行的 command 和 arguments。不进行 shell expansion；如有需要，请使用 ["bash", "-c", "..."]。

events

list[str]

optional

要订阅的 event names。省略或留空即可接收所有 events。

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

上面的第二个 hook 没有 events filter，因此会接收 Deep Agents Code 发出的每个 event。

Payload format

每个 hook command 都会在 stdin 上接收一个 JSON object，其中包含 "event" key 以及 event-specific fields：

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

Events reference

`session.start`

Agent session 开始时触发（interactive 和 non-interactive modes 都会触发）。

thread_id

string

required

Session thread identifier。

`session.end`

Session 退出时触发。

thread_id

string

required

Session thread identifier。

`user.prompt`

Interactive mode 中 user 提交 chat message 时触发。无 additional fields。

`input.required`

Agent 需要 human input（human-in-the-loop interrupt）时触发。无 additional fields。

`permission.request`

一个或多个 tool calls 需要 user permission 时，在 approval dialog 之前触发。

tool_names

list[str]

required

请求 approval 的 tools 名称。

`tool.error`

Tool call 返回 error 时触发。

tool_names

list[str]

required

出错 tool(s) 的名称。

`task.complete`

Agent 完成当前 task 时触发（streaming loop 结束，且没有进一步 interrupts）。

thread_id

string

required

Session thread identifier。

`context.compact`

Deep Agents Code compact（summarize）conversation context 之前触发。无 additional fields。

Execution model

Background thread：Hook subprocesses 通过 asyncio.to_thread 在线程中运行，因此 main event loop 不会被阻塞。
Concurrent dispatch：当多个 hooks 匹配同一 event 时，它们会在线程池中并发运行。
5-second timeout：每个 command 都有 5 秒 timeout。超过此时间的 commands 会被 kill。
Fire-and-forget：Errors 会按 hook 捕获，并以 debug/warning level 记录。失败的 hook 永远不会让 Deep Agents Code 崩溃或停顿。
Lazy loading：Config file 会在首次 event dispatch 时读取一次，并在 session 剩余时间中缓存。
No shell expansion：Commands 会直接执行（不通过 shell）。如果需要 pipes 或 variable expansion 等 shell features，请包装在 ["bash", "-c", "..."] 中。

Hook examples

Log all events to a file

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

Desktop notification on task completion (macOS)

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

Python handler

编写一个 handler script，从 stdin 读取 JSON payload：

my_handler.py

import json
import sys

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)

~/.deepagents/hooks.json

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

Security considerations

Hooks 遵循与 Git hooks 或 shell aliases 相同的 trust model。任何能够写入 ~/.deepagents/hooks.json 的 user 都可以执行任意 commands。这是设计使然：

No command injection：Payload data 只会以 JSON 形式流向 stdin，绝不会进入 command-line arguments。json.dumps 会处理 escaping。
No shell by default：Commands 以 shell=False 运行，防止 shell injection。
Malformed config：Invalid JSON 或 unexpected types 会生成 logged warnings，而不是 security issues。

只添加来自可信来源的 hooks。Hook 拥有与你的用户账号相同的权限。

Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

Edit this page on GitHub or file an issue.

​Provider credentials

​使用 /auth（推荐）

​Environment variables（CI 和 headless）

​Key resolution order

​使用 Tavily 启用 web search

​Environment variables

​Loading order and precedence

​DEEPAGENTS_CODE_ prefix

​Config file

​Default 和 recent model

​Default 和 recent agent

​Provider configuration

​Model constructor params

​Profile overrides（高级）

​向 interactive switcher 添加 models

​Custom base URL

​Compatible APIs

​Arbitrary providers

​Endpoints、keys 和 gateways

​base_url 如何解析

​Overrides 会保持 key 和 endpoint 配对

​Managed gateways

​Skill directory allowlist

​Themes

​User-defined themes

​覆盖 built-in theme colors

​将 themes 映射到 terminals

​Picker shortcuts

​Common TERM_PROGRAM values

​Resolution order

​Auto-update

​Uninstall

​Managed deployments

​Environment variable reference

​External editor

​Hooks

​设置

​Hook configuration

​Payload format

​Events reference

​session.start

​session.end

​user.prompt

​input.required

​permission.request

​tool.error

​task.complete

​context.compact

​Execution model

​Hook examples

​Security considerations

Provider credentials

使用 `/auth`（推荐）

Environment variables（CI 和 headless）

Key resolution order

使用 Tavily 启用 web search

Environment variables

Loading order and precedence

`DEEPAGENTS_CODE_` prefix

Config file

Default 和 recent model

Default 和 recent agent

Provider configuration

Model constructor params

Profile overrides（高级）

向 interactive switcher 添加 models

Custom base URL

Compatible APIs

Arbitrary providers

Endpoints、keys 和 gateways

`base_url` 如何解析

Overrides 会保持 key 和 endpoint 配对

Managed gateways

Skill directory allowlist

Themes

User-defined themes

覆盖 built-in theme colors

将 themes 映射到 terminals

Picker shortcuts

Common `TERM_PROGRAM` values

Resolution order

Auto-update

Uninstall

Managed deployments

Environment variable reference

External editor

Hooks

设置

Hook configuration

Payload format

Events reference

`session.start`

`session.end`

`user.prompt`

`input.required`

`permission.request`

`tool.error`

`task.complete`

`context.compact`

Execution model

Hook examples

Security considerations