配置

通过配置文件、管理员设置、环境变量、hooks 和 CLI 标志来配置 Deep Agents Code

Deep Agents Code 将用户配置存储在其 profile 目录（默认为 ~/.deepagents/）以及项目级的 dotfile 中。管理员可以通过固定系统路径下的 managed_config.toml 强制实施设置。完整的目录树、会话存储和技能路径参见数据位置。

主要的配置文件包括：

•Config file

编辑 config.toml 可设置模型默认值、服务商设置、主题和更新设置。

•Managed configuration

使用 managed_config.toml 为所有用户设置由管理员控制的设置。

•Environment variables

在 ~/.deepagents/.env 中或通过 shell 导出设置全局 API 密钥和机密信息。

•Hooks

在 hooks.json 中将外部命令订阅到生命周期事件。

•MCP servers

在 ~/.deepagents/.mcp.json 中定义全局 MCP 服务器。

•Python extensions

添加自定义工具、middleware 和存储路由。

设置的解析方式

Deep Agents Code 采用分层的配置方式。优先级顺序取决于设置的类型。

常规选项（解释器限制、更新设置、主题以及其他 config.toml 键）按以下顺序采用第一个可用的值：

1. 管理员所有的 managed_config.toml
2. 带 DEEPAGENTS_CODE_ 前缀的环境变量
3. 规范的环境变量（适用时）
4. ~/.deepagents/config.toml
5. 内置默认值

使用 dcode config 或 dcode config get <key> 可查看当前值及其来源。参见查看配置。

服务商 API 密钥采用单独的顺序。参见密钥解析顺序。

Dotenv 文件在启动时加载：先是最近的项目 .env（从启动目录向上逐级查找），然后是 ~/.deepagents/.env。shell 中导出的值始终优先于 .env 中的值。参见加载顺序与优先级。

服务商端点（base_url）与它们相匹配的 API 密钥一起解析。参见端点、密钥与网关。

查看配置

dcode config 系列命令会显示 Deep Agents Code 所使用的设置以及每个值的来源，而无需启动会话。你可以用它们来确认某个管理员设置、环境变量或 config.toml 设置是否处于生效状态。

命令	说明
dcode config	显示每一项设置、其当前值以及该值的来源
dcode config get <key>	显示某一项设置的当前值与来源，例如 dcode config get interpreter.memory_limit_mb
dcode config path	显示 managed_config.toml、config.toml、项目级与全局 .env 文件、hooks.json 以及托管状态的文件位置，并指明每个文件是否存在

为 dcode config 或 dcode config get 加上 --verbose 可显示说明、默认值以及每项设置可以在哪些地方定义。将 --verbose 与 --json 结合使用，还会包含可接受的类型和其他参考细节。这三个命令都接受 --json 以输出机器可读的结果。完整的命令列表参见 CLI 参考。

WARNING

服务商凭据和其他机密信息只会以「已配置 / 未配置」的形式报告。config 或 config get 永远不会打印它们的值。

环境变量

除了在 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 中已经设置的值。

要完全跳过项目级 .env（全局的 ~/.deepagents/.env 仍会加载），请设置 startup.read_project_dotenv。

[startup]
read_project_dotenv = false

该设置会从托管配置、环境变量以及用户的 config.toml 中解析。这些都在应用任何项目级 .env 之前读取，因此项目级 .env 无法为自身关闭（或重新打开）这个开关。

对于来自 dotenv 文件的环境变量，如果它们可能改变可执行文件查找、解释器或 shell 的启动行为、Git 行为或信任设置，Deep Agents Code 会予以忽略。

查看 dotenv 文件中被阻止的环境变量

以下键既不能在项目级 dotenv 文件中设置，也不能在全局 dotenv 文件中设置：

• Profile 与信任根目录：DEEPAGENTS_HOME、DEEPAGENTS_HOME_IS_DEFAULT、DEEPAGENTS_CODE_READ_PROJECT_DOTENV、DEEPAGENTS_INHERITED_PYTHONPATH
• 动态链接器的预加载 / 审计：DYLD_INSERT_LIBRARIES、DYLD_LIBRARY_PATH、LD_AUDIT、LD_LIBRARY_PATH、LD_PRELOAD
• 解释器启动 / 路径：NODE_OPTIONS、PATH、PYTHONEXECUTABLE、PYTHONHOME、PYTHONPATH、PYTHONSTARTUP
• Shell 启动钩子：BASH_ENV、ENV、BASHOPTS、SHELLOPTS、CDPATH、GLOBIGNORE
• 凭据提示劫持：GIT_ASKPASS、SSH_ASKPASS
• Git 配置 / 执行注入：GIT_DIR、GIT_WORK_TREE、GIT_OBJECT_DIRECTORY、GIT_EXEC_PATH、GIT_EDITOR、GIT_PAGER、GIT_SSH、GIT_SSH_COMMAND，以及 GIT_CONFIG_COUNT、GIT_CONFIG_KEY_*、GIT_CONFIG_VALUE_*、GIT_CONFIG_PARAMETERS、GIT_CONFIG_SYSTEM、GIT_CONFIG_GLOBAL 这些前缀族
• Windows 进程变量：COMSPEC、SYSTEMROOT、WINDIR

项目级 .env 还不能设置 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS、DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS、DEEPAGENTS_CODE_AUTO_CLASSIFIER_MODEL、DEEPAGENTS_CODE_AUTO_CLASSIFIER_TIMEOUT、DEEPAGENTS_CODE_FORKED_SUBAGENTS 或 TERM_PROGRAM。请改为在你的 shell 或全局的 ~/.deepagents/.env 中设置这些变量。

WARNING

在不受信任的项目目录中运行 dcode，会让你暴露于由该项目所控制的文件之下。该目录中的恶意 .env、Makefile 或构建脚本都可能影响智能体的进程环境以及它所执行的内容。任何你不会在其中运行任意脚本的目录，都应视为不受信任；对于不受信任的代码仓库，请使用远程沙箱。

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=

技能目录允许列表

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

如果你将共享的技能资源存放在非标准位置，并通过标准技能目录中的符号链接来引用它们，可以把该位置添加到包含关系允许列表中。这不会新增一个技能发现位置：技能仍然只会从标准目录中被发现。

string[]

添加到技能包含关系允许列表中的路径。支持 ~ 展开。

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

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

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

设置该环境变量时，它的优先级高于配置文件中的值。更改会在 /reload 后生效。

Profile 目录位置（DEEPAGENTS_HOME）

DEEPAGENTS_HOME 用于选择 Deep Agents Code 用作用户 profile 的目录——通常存储在 ~/.deepagents/ 下的一切内容都会转移到所配置的路径下。这包括 config.toml、全局 .env、~/.deepagents/.mcp.json 和 hooks.json、extensions/、按智能体划分的目录（AGENTS.md、skills/、memories/、agents/）、插件，以及 .state/（会话、输入历史、凭据和锁）。未设置时，profile 默认为 ~/.deepagents。

有效的形式包括绝对路径，或以 ~/ 开头的路径：

export DEEPAGENTS_HOME="~/profiles/work"        # resolved against your home directory
export DEEPAGENTS_HOME="/opt/dcode-profiles/work"  # absolute; works even with no resolvable home

相对路径和 ~user 形式会被拒绝。解析后的路径还不得是文件系统根目录、主目录本身、已存在的非目录项、不可读或不可搜索的目录，或指向缺失目标的符号链接——这些情况会在启动时报错并失败。

WARNING

DEEPAGENTS_HOME 是一条信任边界：它决定了 Deep Agents Code 将哪些 config.toml、.env 和 .mcp.json 视为用户可信。它必须在继承而来的 shell 环境中设置（例如，在启动之前执行 export DEEPAGENTS_HOME=...）。它在启动时、加载 dotenv 之前被捕获，并且任何 .env 文件都不得设置或更改它——否则，一个由项目控制的 .env 就可能把信任根目录重新定位到它所控制的文件上。子进程会继承解析后的路径。

别名 ~/.agents/skills/（在各类 AI CLI 工具之间共享）是从启动时的主目录解析的，而不是从 DEEPAGENTS_HOME 解析。完整的目录树参见数据位置。

主题

使用 /theme 可打开交互式主题选择器。在列表中浏览即可实时预览主题，按 Enter 会将你的选择持久化到 config.toml。

Deep Agents Code 内置了许多主题。默认主题是 langchain，这是一个带有 LangChain 品牌配色的深色主题。所选主题会保存在 [ui] 下：

[ui]
theme = "langchain-dark"

关于用户自定义主题、内置覆盖以及针对特定终端的映射，参见配置文件中的 [themes.*] 和 [ui.terminal_themes] 部分，或直接在 config.toml 中进行配置：

用户自定义主题、覆盖与终端映射

用户自定义主题

在 config.toml 中的 [themes.<name>] 段下定义自定义主题。每个段都需要 label（str）。dark（bool）若省略则默认为 false —— 深色主题请设置为 true。所有颜色字段均为可选 —— 省略的字段会根据 dark 标志回退到内置的深色或浅色调色板。

[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 选择器中。

覆盖内置主题颜色

若要在不创建新主题的情况下调整某个内置主题的颜色，可使用 [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"

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

常见的 TERM_PROGRAM 值

终端	TERM_PROGRAM
Apple Terminal	Apple_Terminal
iTerm2	iTerm.app
WezTerm	WezTerm
VS Code 集成终端	vscode
Ghostty	ghostty

主题解析顺序

1. DEEPAGENTS_CODE_THEME 环境变量（显式覆盖）。
2. 针对当前 TERM_PROGRAM 的 [ui.terminal_themes] 映射。
3. [ui] theme 已保存的偏好设置（由 /theme 设置）。
4. 内置默认值（langchain）。

自动更新

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

要退出自动更新：

[update]
auto_update = false

环境变量优先于配置文件。将环境变量设置为空值会禁用该功能。

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

定价目录自动更新

Deep Agents Code 会在后台每小时从上游刷新其模型定价目录，以确保成本估算保持最新。要退出：

[update]
prices_auto_update = false

自定义定价覆盖

对于目录未覆盖的模型，请将费率添加到 ~/.deepagents/prices.json。该文件使用 genai-prices 的服务商数组 schema。例如：

[
  {
    "id": "my-provider",
    "name": "My provider",
    "api_pattern": "gateway\\.example\\.com",
    "models": [
      {
        "id": "my-model",
        "match": { "equals": "my-model" },
        "prices": { "input_mtok": 2.5, "output_mtok": 10.0 }
      }
    ]
  }
]

费率以每百万 token 的美元计。编辑文件后请重启 Deep Agents Code。自定义费率仅在 genai-prices 目录不包含该模型时生效。

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

[update]
check = false

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

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

升级后，Deep Agents Code 会在下次启动时显示一个“新特性”横幅，其中包含指向变更日志的链接。

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

显示选项

这些 [ui] 键用于调整终端 UI 显示的内容。

会话用量统计

Deep Agents Code 会在会话结束时显示会话用量统计（默认开启）：

[ui]
show_usage_stats = false

环境变量优先；将其设置为空值也会禁用统计信息。

折叠大型粘贴内容

粘贴到聊天输入框中的大型内容会被折叠为紧凑的占位符（默认开启）。要让粘贴的完整文本保持可见：

[ui]
collapse_pastes = false

自动记忆

Deep Agents Code 会自动将学习内容保存到记忆中。要在停止自动保存的同时继续加载记忆，请更改自动记忆设置：

[memory]
auto_save = false

你仍可使用 /remember 显式保存记忆。环境变量优先于配置文件。

对话历史保留

使用 /offload 卸载线程会在 ~/.deepagents/conversation_history/ 下写入一个 markdown 归档。启动清理会删除超过 30 天的归档。该清理只处理归档目录直接包含的常规 .md 文件，绝不阻塞启动，并记录后吞掉文件系统错误。

更改保留窗口，或用 0 禁用清理：

[history]
retention_days = 90   # 0 disables the sweep

环境变量优先于配置文件。使用 DEEPAGENTS_HOME 配置文件时，归档位于 $DEEPAGENTS_HOME/conversation_history/ 下。

恢复时压缩

恢复线程会恢复其完整上下文，因此下一轮会为此付出代价。当恢复的线程的上下文超过阈值时，Deep Agents Code 会在你的下一条消息之前建议对其进行压缩；拒绝不会有代价，且 /compact（或 /offload）仍然可用。默认阈值为 400,000 token；将其设置为 0 可禁用该建议：

[threads]
compact_on_resume_threshold = 200000

卸载

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

uv tool uninstall deepagents-code

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

rm -rf ~/.deepagents

托管配置

托管配置允许管理员在整个设备群范围内控制 Deep Agents Code 的设置。Deep Agents Code 会在用户环境变量和配置之前检查管理员拥有的 managed_config.toml，因此用户无法覆盖其中定义的设置。

找到托管配置文件

Deep Agents Code 会在每个操作系统上的固定位置查找 managed_config.toml：

操作系统	路径
macOS	/Library/Application Support/dcode/managed_config.toml
Linux	/etc/dcode/managed_config.toml
Windows	<ProgramData>\dcode\managed_config.toml

在 Windows 上，Deep Agents Code 通过系统注册表而非 %ProgramData% 环境变量来查找 ProgramData。环境变量无法更改托管配置的位置。如果注册表不可用，Deep Agents Code 会检查 C:\ProgramData\dcode\managed_config.toml。如果该文件也缺失，Deep Agents Code 就无法确定管理员是否配置了策略，因此使用配置的命令会停止运行，而不是在缺少该配置的情况下运行。

创建托管策略

使用与 ~/.deepagents/config.toml 相同的 TOML 段和键。运行 dcode config --verbose --json 可查看可用的设置、它们接受的类型，以及它们是否可在配置文件中设置。

例如，以下策略会固定为手动审批模式，从 Shift+Tab 模式循环中移除 YOLO，限制 shell 自动审批，限制模型使用，禁用 JavaScript 解释器，并启用客户端 LangSmith 机密信息脱敏：

[startup]
mode = "manual"
yolo_switcher = false

[shell]
allow_list = ["git", "make"]

[models]
allowed = ["acme:production", "openai:*"]

[interpreter]
enable_interpreter = false

[tracing]
langsmith_redact = true

只有管理员才应拥有编辑此文件的权限。Deep Agents Code 将其视为只读。用户仍可将偏好设置保存到 config.toml，但管理员设置会一直生效，直到它们从 managed_config.toml 中移除。

限制模型使用

将 [models].allowed 设置为精确、区分大小写的 provider:model 规范，或使用 provider:* 允许某个服务商下所有可发现的模型。该允许列表适用于启动默认值、--model、/model、已保存的默认值、Auto 分类器、评分标准评分器，以及显式的本地子智能体模型。

[models]
allowed = [
    "acme:production",
    "openai:*",
]
default = "acme:production"
auto_classifier = "openai:gpt-5.5"

如果省略 allowed，用户可以选择任何模型。空列表会阻止所有模型。如果用户的列表无效，Deep Agents Code 会阻止所有模型。如果管理员的列表无效，Deep Agents Code 会阻止启动、重载以及其他使用配置的命令。管理员的列表会替换用户的列表，而不是与之合并。托管的 default、recent 和 auto_classifier 值也必须出现在管理员的允许列表中。

在 [models.providers.<name>].models 下添加模型会使其可供选择，但不会自动允许它。请将确切的模型或服务商通配符添加到允许列表。通配符仅覆盖该服务商可用的模型。如果没有可用的模型，Deep Agents Code 就无法选择默认值。当 Deep Agents Code 能够识别在界面中输入的裸模型名称对应的服务商时，它会在检查允许列表之前将该名称转换为 provider:model。

WARNING

[sandboxes].default 会在用户使用 --sandbox 启动时选择后端。它不会强制进行沙箱化。不带 --sandbox 的启动会在主机上运行，并报告其未使用托管后端。

远程加载策略

你可以将策略存储在中央服务器上，同时将其位置保存在本地的 managed_config.toml 中：

[managed_config]
source = "https://config.example.com/dcode-policy.toml"

当你配置远程策略时，本地文件只能包含 [managed_config].source 设置。请将完整策略放入远程 TOML 文件。Deep Agents Code 不会合并远程和本地策略设置，且远程文件不能指向另一个源。

查看远程策略要求

URL 必须使用 HTTPS，不包含凭据或查询参数，且不超过 2,048 个 ASCII 字符。Deep Agents Code 不会跟随重定向、使用代理环境变量，也不会将远程策略保存到磁盘。

服务器必须返回一个非空 UTF-8 TOML 文件，HTTP 状态为 200，无压缩，最大大小为 1 MiB。请求在五秒后超时。

WARNING

SSL_CERT_FILE 和 SSL_CERT_DIR 可以改变 Python 信任哪些证书颁发机构。请确保用户无法为 Deep Agents Code 进程更改这些变量。

验证托管策略

在部署或更改策略后，使用配置和诊断命令：

dcode config path
dcode config
dcode config get startup.mode
dcode doctor

dcode config path 会显示托管文件的位置以及 Deep Agents Code 能否读取它。dcode config 和 dcode config get 会将来自该文件的设置标记为 managed config。dcode doctor 会列出解析错误、无效值以及需要修正的设置。对于远程策略，它还会显示本地文件和远程 URL。如果更新失败，它会确认会话是否继续使用之前有效的策略。

修复无效策略

当 Deep Agents Code 无法读取或解析托管文件、无法下载完整的远程策略，或无法安全地应用策略时，它会停止运行，而不是在缺少必需的管理员设置的情况下运行。使用配置的命令会以代码 78 退出。你仍可运行 dcode config、dcode doctor、dcode auth path 和帮助命令来排查该问题。

如果更新在运行中的会话期间失败，Deep Agents Code 会继续使用之前有效的策略并报告该失败。新进程只有在能够加载有效策略时才能启动。

查看失效关闭（fail closed）的设置

以下任一设置的值无效都会停止启动，因为回退到用户值可能会移除某个必需的约束：

• interpreter.enable_interpreter
• interpreter.ptc
• interpreter.ptc_acknowledge_unsafe
• models.allowed
• models.auto_classifier
• runtime.recursion_limit
• sandboxes.default
• shell.allow_list
• skills.extra_allowed_dirs
• startup.mode
• startup.yolo_switcher
• tracing.langsmith_redact

如果已知的配置段具有错误的 TOML 结构，也会停止启动。对于其他设置，Deep Agents Code 会忽略无效的管理员值，使用下一个有效来源，并在 dcode config 和 dcode doctor 中列出被忽略的设置。

托管部署

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

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

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

非 root 安装不受影响：当不以 root 身份运行时，所有 root 专属的代码路径都会短路。

使用环境变量固定安装版本

安装脚本会读取一些环境变量，让你可以固定版本、选择 extras，并在整个设备群范围内选择 Python 版本。请在管道安装的同一行中设置它们：

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

string

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

string

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

string

要安装的以逗号分隔的 pip extras，例如 ollama、ollama,groq 或 daytona。可用的 extras 参见 pyproject.toml。

string默认 3.13

安装时要使用的 Python 版本。

string

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

string

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

string

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

托管安装默认启用自动更新。要为每个用户控制更新，请在 managed_config.toml 中设置 [update] auto_update = false 或 [update] check = false。对于其他安装，请使用 DEEPAGENTS_CODE_AUTO_UPDATE=0、DEEPAGENTS_CODE_NO_UPDATE_CHECK=1，或 ~/.deepagents/config.toml 中的相应设置。

要将每个用户的模型流量路由到托管网关（在整个设备群范围内配置网关密钥和 base URL），请参阅托管网关。

环境变量参考

所有 Deep Agents Code 专属的环境变量都使用 DEEPAGENTS_CODE_ 前缀。关于该前缀如何也能作为第三方凭据的覆盖方式，请参阅 DEEPAGENTS_CODE_ 前缀。

string

切换 Deep Agents Code 的自动更新。默认启用；设置为 0、false、no 或 off（或空值）以退出。

integer

Auto 模式分类器审查每批受控动作的时间预算（秒）。有效范围：1–300。超出范围或非整数值会回退到默认值（20）。在提高此值之前，请考虑选择更快的分类器模型。覆盖 config.toml 中的 [models].auto_classifier_timeout。参见 Auto 分类器超时。

string

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

string

选择启用实验性的、不稳定的 Deep Agents Code 行为。设置为 1（或任何真值）以启用实验性功能。

string默认 true

为所有来源（包括 -e / --extension）启用或禁用 Python 扩展发现。覆盖 config.toml 中的 [extensions].enabled。仍然需要 DEEPAGENTS_CODE_EXPERIMENTAL=1。

string默认 "ask"

将默认的项目扩展信任策略设置为 ask、always 或 never。覆盖 config.toml 中的 [extensions].trust。仅当你打开的每个项目都受信任时才使用 always。

string默认 /tmp/deepagents_debug.log

调试日志文件的路径。

NOTE

下面的项目 MCP 信任变量需要 deepagents-code>=0.1.40。此版本会忽略先前的 DEEPAGENTS_CODE_ENABLED_PROJECT_MCP_SERVERS 变量；如需相同的基于名称的行为，请使用 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS。

string

要始终按名称拒绝的、以逗号分隔的项目 MCP 服务器名称。Deep Agents Code 会将这些名称与 [mcp].disabled_project_servers 合并；拒绝优先于已保存的审批和 --trust-project-mcp 标志。

string

要为任何项目按名称预先批准的、以逗号分隔的项目 MCP 服务器名称。这是一个进程级的逃生通道：同一服务器名称下的不同项目、命令变更或 URL 变更仍然会匹配。设置后，该变量会替换该进程已保存的审批。尽可能优先使用项目 MCP 提示中已保存的审批。

string默认 true

将聊天输入框中的大型粘贴内容折叠为紧凑的占位符。设置为假值（或空值）可让粘贴的完整文本保持可见。覆盖 [ui].collapse_pastes。参见折叠大型粘贴内容。

string

要以冒号分隔并添加到技能隔离允许列表的路径。

string默认 true

让内置的 general-purpose 子智能体继承父对话和系统提示词。设置为 0、false、no 或 off（或空值）以使用隔离模式。请在 shell 或全局 ~/.deepagents/.env 中设置此变量；Deep Agents Code 会在项目 .env 文件中忽略它，因为继承可能包含父级的私有状态。参见继续父对话。

integer默认 30

已卸载的对话历史归档在启动清理删除它之前保留的天数；0 禁用清理。覆盖 [history].retention_days。参见对话历史保留。

string

覆盖 Deep Agents Code 自身智能体追踪所使用的 LangSmith 项目名称。Shell 命令仍使用用户原始的 LANGSMITH_PROJECT 运行，因此应用、测试或脚本的追踪可能出现在单独的项目中。参见使用 LangSmith 追踪。

string默认 true

切换 Deep Agents Code 的 LangSmith 智能体追踪输入输出的客户端机密信息脱敏。默认启用。接受 1、true、yes 或 on 以启用脱敏，接受 0、false、no 或 off 以禁用它，不区分大小写。当启用脱敏时，如果无法配置脱敏，则该次运行的追踪会被禁用。参见配置 LangSmith 追踪脱敏。

string

一个同时将智能体追踪写入其中的第二个 LangSmith 项目。当设置且追踪处于活动状态时，每次智能体运行都会双重写入主项目（来自 DEEPAGENTS_CODE_LANGSMITH_PROJECT，或默认为 deepagents-code）和此项目。默认关闭。参见使用 LangSmith 追踪。

string默认 true

让智能体主动将学习内容保存到记忆中。设置为假值（或空值）可在继续加载记忆的同时停止未经提示的自动保存；显式保存仍然有效。覆盖 [memory].auto_save。参见自动记忆。

string

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

string

选择用户配置文件和信任根目录，而不是默认的 ~/.deepagents。接受绝对路径或以 ~/ 开头的路径；~user 形式和相对路径会被拒绝。必须在继承的 shell 环境中设置 —— 任何 .env 文件都不得设置它。参见配置文件位置。

string

覆盖首次运行引导流程。设置为真值可强制在每次启动时打开它；设置为假值可完全禁止它（对 CI 和预配置的机器很有用）。保持未设置以使用默认的首次运行行为。

string默认 true

在后台每小时从上游刷新模型定价目录。设置为假值（或空值）以退出。覆盖 [update].prices_auto_update。参见定价目录自动更新。

string默认 true

将项目 .env（从工作目录向上查找得到）加载到进程环境中。设置为假值可跳过不受信任仓库的文件；全局 ~/.deepagents/.env 仍会加载。覆盖 [startup].read_project_dotenv。参见加载顺序与优先级。

integer默认 20

在线程列表和选择器中加载并显示的最近线程的最大数量。低于 1 的值会被钳制为 1，非整数值使用默认值。-n 或 --limit 会为 dcode threads list 覆盖此值。

integer

LangGraph 图步骤预算，即 dcode 智能体图每轮可执行的节点调用最大数量。无效值会记录警告，解析会继续到下一个来源。未设置时，Deep Agents Code 会继承 LANGGRAPH_DEFAULT_RECURSION_LIMIT，或将限制留给 LangGraph 服务器。参见智能体运行时限制。

integer

当没有 Deep Agents 递归限制来源胜出时继承的上游 LangGraph 图步骤预算。请在 shell 或全局 ~/.deepagents/.env 中设置它。Deep Agents Code 会在项目 .env 中忽略它，因为它绕过了有界的 runtime.recursion_limit 解析器。参见智能体运行时限制。

string

要允许的以逗号分隔的 shell 命令（或 recommended / all）。

string默认 false

在交互式记录中以及非交互模式下的 stderr 中显示服务商可见的推理内容。覆盖 [ui].show_reasoning；对于单次启动，--show-reasoning 优先。参见显示服务商可见的推理内容。

string默认 true

在会话结束时显示会话用量统计。设置为假值（或空值）以隐藏它们。覆盖 [ui].show_usage_stats。参见会话用量统计。

string

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

使用 dcode doctor 运行诊断

当 Deep Agents Code 无法正常启动、服务商或 MCP 服务器无法连接、追踪配置错误，或安装或更新看起来有问题时，请使用 dcode doctor。它会在不启动会话的情况下运行诊断，并总结当前的运行时状态。

# Show diagnostics in the terminal
dcode doctor

输出：

  Diagnostics ✓
  ├ deepagents-code: 0.1.30
  ├ deepagents (SDK): 0.7.0
  ├ Commit hash: e4709c2
  ├ Python: 3.13.11
  ├ Platform: darwin-arm64
  ├ Install method: uv
  └ Path: /Users/naomi/.local/share/uv/tools/deepagents-code

  Updates ✓
  ├ Update checks: enabled
  ├ Auto-updates: enabled
  ├ Latest version: up to date
  └ Last checked: 21m ago

  Tracing ✓
  ├ Tracing: enabled
  ├ Credentials: configured
  ├ Project: shared-deepagents
  └ Endpoint: https://api.smith.langchain.com

  Configuration ✓
  ├ Data directory: /Users/naomi/.deepagents (exists)
  └ Config file: /Users/naomi/.deepagents/config.toml (exists)

  Tip: Run `dcode config` or `dcode config get <key>` to drill into config details.
       Run `dcode --version` (or `dcode -v`) for dependency versions.

TIP

将 dcode doctor 与 dcode config 配合使用，以检查整体健康状况并查看某个特定设置来自何处。

数据位置

Deep Agents Code 将数据存储在两个目录层级中：

• ~/.deepagents/ — Deep Agents 专属数据（智能体记忆、技能、会话）。可用 DEEPAGENTS_HOME 重定位；此时下列路径将改为以该目录为根。
• ~/.agents/ — 与工具无关的数据（在多个 AI CLI 工具之间共享的技能）

目录结构

~/.deepagents/
├── .state/                  # Per-machine Deep Agents Code state (managed automatically)
│   ├── sessions.db          #   SQLite database for conversation checkpoints
│   ├── history.jsonl        #   Command input history
│   ├── chatgpt-auth.json    #   ChatGPT OAuth token for the openai_codex provider
│   ├── ...                  #   Other markers & credentials
├── extensions/              # User-wide Python extensions (experimental)
└── {agent}/                 # Per-agent directory (default: "agent")
    ├── AGENTS.md            # User customizations to agent instructions
    ├── skills/              # User-level skills
    │   └── {skill-name}/
    │       └── SKILL.md
    └── agents/              # Custom subagent definitions
        └── {subagent-name}/
            └── AGENTS.md

~/.agents/                   # Tool-agnostic alias (shared across AI CLIs)
└── skills/                  # Skills available to any compatible tool
    └── {skill-name}/
        └── SKILL.md

{project}/                   # Project-level (in git repo root)
├── AGENTS.md                # Project instructions (root-level)
└── .deepagents/
│   ├── AGENTS.md            # Project instructions (preferred location)
│   ├── extensions/          # Project Python extensions (requires trust; experimental)
│   ├── skills/              # Project-specific skills
│   │   └── {skill-name}/
│   │       └── SKILL.md
│   └── agents/              # Project-specific subagents
│       └── {subagent-name}/
│           └── AGENTS.md
└── .agents/                 # Tool-agnostic project skills
    └── skills/
        └── {skill-name}/
            └── SKILL.md

各类数据放在哪里

数据	位置	读/写	说明
会话	~/.deepagents/.state/sessions.db	读写	SQLite 检查点数据库
输入历史	~/.deepagents/.state/history.jsonl	读写	JSON-lines 格式，上/下方向键="true" 回看
ChatGPT OAuth token	~/.deepagents/.state/chatgpt-auth.json	读写	为 openai_codex 服务商提供凭据；在使用 ChatGPT 登录时创建，并自动刷新。仅你的用户账户可读。
基础指令	包内 default_agent_prompt.md	读	不可修改，随 Deep Agents Code 升级而更新
用户自定义	~/.deepagents/{agent}/AGENTS.md	读写	追加到基础指令之后
项目指令	.deepagents/AGENTS.md 或 AGENTS.md	读	两者都存在时都会加载
用户技能	~/.deepagents/{agent}/skills/	读写	智能体专属技能
共享技能	~/.agents/skills/	读	与工具无关，跨 CLI 共享
项目技能	.deepagents/skills/ 或 .agents/skills/	读	项目范围内
用户 Python 扩展	~/.deepagents/extensions/	读写	实验性；见 Python 扩展
项目 Python 扩展	.deepagents/extensions/	读	实验性；需要项目信任
自定义子智能体	~/.deepagents/{agent}/agents/	读写	用户定义的子智能体
项目子智能体	.deepagents/agents/	读	项目定义的子智能体

优先级规则

当同一项存在于多个位置时，优先级更高者完全生效（不做合并）。

技能

优先级顺序（从低到高）：

1. ~/.deepagents/{agent}/skills/ — 用户级 Deep Agents Code
2. ~/.agents/skills/ — 用户级、与工具无关
3. .deepagents/skills/ — 项目级 Deep Agents Code
4. .agents/skills/ — 项目级、与工具无关 （最高）

加载技能时，Deep Agents Code 会校验解析后的文件路径仍位于上述目录之一内。解析结果落在所有技能根目录之外的符号链接会被拒绝。若要允许符号链接指向其他目录，见 [skills].extra_allowed_dirs。

子智能体

优先级顺序（从低到高）：

1. ~/.deepagents/{agent}/agents/ — 用户级
2. .deepagents/agents/ — 项目级 （最高）

每个子智能体都是一个 AGENTS.md 文件，包含 YAML frontmatter（name、description，以及可选的 model）与作为系统提示词的 markdown 正文。完整格式参考见在 Deep Agents Code 中使用子智能体。

指令

所有指令来源都会被合并（而非覆盖）：

1. 包内基础提示词 （始终加载）
2. ~/.deepagents/{agent}/AGENTS.md （追加）
3. .deepagents/AGENTS.md （追加）
4. 项目根目录的 AGENTS.md （追加）

.deepagents 与 .agents 的区别

目录	用途	何时使用
.deepagents/	Deep Agents Code 专属	使用 Deep Agents Code 专有功能的技能与配置
.agents/	与工具无关	你希望在多个 AI CLI 工具之间共享的技能

TIP

能配合任意 AI 编码助手使用的技能，请放在 .agents/skills/。 依赖 Deep Agents 专有工具或约定的技能，请放在 .deepagents/skills/。

清理数据

需求	操作
重置全部数据	rm -rf ~/.deepagents
仅清除会话	rm ~/.deepagents/.state/sessions.db*
清除输入历史	rm ~/.deepagents/.state/history.jsonl
清除已存储的 API 密钥	rm ~/.deepagents/.state/auth.json
清除 MCP OAuth token	rm -rf ~/.deepagents/.state/mcp-tokens
清除已保存的 MCP 项目批准	从 ~/.deepagents/config.toml 的 [mcp] 表中删除 enabled_project_server_approvals
重新运行首次引导	rm ~/.deepagents/.state/onboarding_complete
重置智能体指令	dcode agents reset --agent {name}
移除某个技能	rm -rf ~/.deepagents/{agent}/skills/{skill-name}

WARNING

删除 ~/.deepagents/.state/sessions.db 会移除全部对话历史与检查点。

除非你有 sessions.db 文件的备份，否则此操作无法撤销。

另请参阅

• 服务商凭据
• 配置文件
• CLI 参考
• 钩子
• 数据位置
• MCP 工具
• Python 扩展

---