Deep Agents Code 的配置存储在 ~/.deepagents/ 目录和项目级别的点文件中。有关完整的目录结构、会话存储和技能路径,请参见数据位置。 主要配置文件如下:

配置文件

编辑 config.toml 以设置模型默认值、提供商设置、主题和更新设置。

环境变量

在 ~/.deepagents/.env 或 shell export 中设置全局 API 密钥和机密。

钩子

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

MCP 服务器

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

设置如何解析

Deep Agents Code 会从多个来源合并设置。哪个来源优先取决于设置类型。 常规选项(解释器限制、更新设置、主题以及其他 config.toml 键)按以下顺序解析:
  1. 以 DEEPAGENTS_CODE_ 为前缀的环境变量
  2. 标准环境变量(如适用)
  3. ~/.deepagents/config.toml
  4. 内置默认值
使用 dcode config show 或 dcode config get <key> 来查看有效值及其来源。参见检查配置。 供应商 API 密钥使用单独的顺序。参见密钥解析顺序。 Dotenv 文件在启动时加载:先加载最近的项目 .env(从启动目录向上遍历),然后是 ~/.deepagents/.env 作为所有项目的全局后备。Shell export 的值始终优先于 .env 值。参见加载顺序和优先级。 供应商端点 (base_url) 与其匹配的 API 密钥一起解析。参见端点、密钥和网关。

检查配置

dcode config 命令组可以报告当前生效的配置以及每个值的来源,而无需启动会话。这对于确认环境变量或 config.toml 设置是否被正确拾取,以及在错误报告中共享经过编辑的快照非常有用。 所有四个命令都接受 --json 参数以获得机器可读的输出。有关管理子命令的完整列表,请参见 CLI 参考。
提供商凭证和其他机密只会报告为已配置/未配置——它们的值永远不会被 config show 或 config get 打印出来,因此将输出粘贴到错误报告中是安全的。

环境变量

除了 shell export,Deep Agents Code 还从 dotenv 文件读取环境变量,因此您可以将 API 密钥排除在 shell 配置文件之外,并避免在项目间重复 .env 文件。
~/.deepagents/.env
有关供应商密钥的具体信息,请参见供应商凭证。

加载顺序和优先级

在启动时,Deep Agents Code 会读取最近的项目 .env 文件,通过搜索启动目录并向上遍历其父目录来找到(找到的第一个 .env 生效),然后将 ~/.deepagents/.env 作为所有项目的全局后备。项目 .env 优先于全局 .env,并且两者都不会覆盖您 shell 中已设置的值。运行 /reload 会重新读取两个 .env 文件,因此您可以在不重启的情况下更改密钥,但 shell 的值仍然优先。这适用于 Deep Agents Code 读取的每个变量(例如,TAVILY_API_KEY 或 DEEPAGENTS_CODE_* 设置),除了 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS 和 DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS。Deep Agents Code 会忽略项目 .env 中的这些项目 MCP 信任设置,因此仓库无法批准自己的服务器。请在您的 shell 或全局 ~/.deepagents/.env 中设置它们。
在不受信任的项目目录中运行 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}:
~/.deepagents/.env

技能目录白名单

默认情况下,当 Deep Agents Code 加载技能时,它会验证解析后的技能文件路径是否位于标准技能目录之一内。这可以防止技能目录中的符号链接读取这些根目录之外的任意文件。 如果您将共享技能资产存储在非标准位置,并从标准技能目录使用符号链接引用它们,您可以将该位置添加到内容白名单中。这不会添加新的技能发现位置:技能仍然只从标准目录中发现。
string[]
optional
添加到技能内容白名单的路径。支持 ~ 扩展。
或者,将 DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS 环境变量设置为冒号分隔的列表:
当设置该环境变量时,它优先于配置文件中的值。更改在 /reload 后生效。

主题

使用 /theme 打开一个交互式主题选择器。浏览列表可实时预览主题,按 Enter 可将您的选择持久化到 config.toml。 Deep Agents Code 附带许多内置主题。默认主题是 langchain,这是一个带有 LangChain 品牌颜色的深色主题。选定的主题会持久保存在 [ui] 下:
有关用户定义的主题、内置覆盖以及特定终端映射,请参见配置文件中的 [themes.*] 和 [ui.terminal_themes] 部分,或直接在 config.toml 中配置它们:

用户定义主题

在 config.toml 的 [themes.<name>] 部分下定义自定义主题。每个部分都需要 label(字符串)。如果省略,dark(布尔值)默认为 false — 对于深色主题请设置为 true。所有颜色字段都是可选的 — 省略的字段将根据 dark 标志回退到内置的深色或浅色调色板。
用户定义的主题会与内置主题一起出现在 /theme 选择器中。

覆盖内置主题颜色

要调整内置主题的颜色而不创建新主题,请使用 [themes.<builtin-name>] 部分。只读取颜色字段 — label 和 dark 从内置主题继承:
省略的颜色字段将保留现有的内置值。对 [themes.*] 部分的更改在 /reload 后生效。

将主题映射到终端

如果您在不同配色方案的终端之间切换(例如,深色 iTerm 和浅色 Apple Terminal),可以在 [ui.terminal_themes] 下将每个终端映射到一个主题。Deep Agents Code 会匹配 shell 的 TERM_PROGRAM 并自动应用映射的主题:
在 /theme 选择器中按 T 可以为当前终端保存高亮主题,或者运行 echo $TERM_PROGRAM 来找到您终端的标识符并手动添加。

常见 TERM_PROGRAM 值

主题解析顺序

  1. DEEPAGENTS_CODE_THEME 环境变量(显式覆盖)。
  2. 当前 TERM_PROGRAM 的 [ui.terminal_themes] 映射。
  3. [ui] theme 保存的偏好(通过 /theme 设置)。
  4. 内置默认值(langchain)。

自动更新

Deep Agents Code 默认会自动检查并安装更新。 要选择退出自动更新:
环境变量优先于配置文件。 当启用(默认)时,Deep Agents Code 会在会话开始时检查 PyPI 是否有新版本并自动升级。当禁用时,Deep Agents Code 会显示一个更新提示,并附带适当的安装命令。 要完全禁止自动更新检查:
禁用更新检查也会阻止启动时的自动更新安装。 您仍然可以随时使用 /update 斜杠命令手动检查并安装更新,该命令会运行按需检查并内联报告成功或失败。 升级后,Deep Agents Code 会在下次启动时显示一个“新功能”横幅,其中包含指向更新日志的链接。 在会话退出时,如果在会话期间检测到新版本,会显示一个更新横幅作为提醒。

卸载

要删除 dcode 和 deepagents-code 二进制文件以及隔离的工具环境,请运行:
卸载命令不会删除用户配置或会话数据。Deep Agents Code 将这些文件存储在 ~/.deepagents/ 下,包括 config.toml、hooks.json、全局 .env 以及 .state/ 内容(如已保存的会话和凭证)。要同时删除这些数据,请运行:

受管部署

安装脚本支持以 root 身份运行,目标是 macOS MDM 工具(Kandji, Jamf 等),这些工具在最小化的 root 环境中执行脚本。 当 id -u 为 0 时,脚本会:
  1. 通过 /dev/console 或扫描 /Users 目录来解析真实控制台用户的 HOME
  2. 在每个安装步骤之后,将所有创建的文件 chown 回目标用户
非 root 安装不受影响:所有特定于 root 的代码路径在不以 root 身份运行时都会短路。

使用环境变量固定安装

安装脚本读取环境变量,让您可以固定版本、选择附加组件并在整个设备群中选择 Python 版本。在管道安装的同一行设置它们:
string
optional
要安装的确切包版本,例如 0.1.0(或预发布版本如 0.1.0rc1)。与 DEEPAGENTS_CODE_PRERELEASE 互斥 — 同时设置两者是错误的,因为精确固定已经选择了一个版本。
string
optional
解析最新版本时应用的 uv 预发布策略:disallow、allow、if-necessary、explicit 或 if-necessary-or-explicit。与 DEEPAGENTS_CODE_VERSION 互斥。
string
optional
以逗号分隔的 pip 附加组件,例如 ollama、ollama,groq 或 daytona。有关可用的附加组件,请参见 pyproject.toml。
string
default:"3.13"
optional
用于安装的 Python 版本。
string
optional
设置为 1 可跳过可选工具检查。
string
optional
设置为 1 可显示 uv 的原始 stderr(时间行、未过滤的包差异)以及默认安静的状态行(可选工具检查、安装后页脚)。在调试安装时很有用。
string
optional
uv 二进制文件的路径。如果未设置,则自动检测。
受管安装默认启用自动更新。要选择退出,请在用户的 shell 配置文件中设置 DEEPAGENTS_CODE_AUTO_UPDATE=0,或者部署一个包含 [update] auto_update = false 的 config.toml 到 ~/.deepagents/config.toml。要完全禁止自动更新和更新检查,请设置 DEEPAGENTS_CODE_NO_UPDATE_CHECK=1 或部署 [update] check = false。 要将每个用户的模型流量通过受管网关(在设备群范围内配置网关密钥和基本 URL),请参见受管网关。

环境变量参考

所有 Deep Agents Code 特有的环境变量都使用 DEEPAGENTS_CODE_ 前缀。有关前缀如何也用作第三方凭证的覆盖机制,请参见 DEEPAGENTS_CODE_ 前缀。
string
optional
切换自动 Deep Agents Code 更新。默认启用;设置为 0、false、no 或 off 以选择退出。
string
optional
启用详细调试日志记录到文件。接受 1、true、yes、on(不区分大小写)作为启用;0、false、no、off、空字符串或未设置则禁用。启用时,每个会话的服务器日志文件将在关闭时保留,其路径将打印到 stderr 以便诊断。
string
optional
选择加入实验性、不稳定的 Deep Agents Code 行为。设置为 1(或任何真值)以启用实验性功能。
string
default:"/tmp/deepagents_debug.log"
optional
调试日志文件的路径。
下面的项目 MCP 信任变量需要 deepagents-code>=0.1.40。此版本忽略了之前的 DEEPAGENTS_CODE_ENABLED_PROJECT_MCP_SERVERS 变量;使用 DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS 获得相同的基于名称的行为。
string
optional
以逗号分隔的项目 MCP 服务器名称,始终按名称拒绝。Deep Agents Code 将这些名称与 [mcp].disabled_project_servers 组合;拒绝优先于已保存的批准和 --trust-project-mcp 标志。
string
optional
以逗号分隔的项目 MCP 服务器名称,用于预批准任何项目的名称。这是一个进程范围的转义符:同一服务器名称下的不同项目、命令更改或 URL 更改仍会匹配。设置后,此变量将替换进程的已保存批准。尽可能使用项目 MCP 提示的已保存批准。
string
optional
以冒号分隔的路径,添加到技能内容白名单。
string
optional
覆盖 Deep Agents Code 自身代理跟踪的 LangSmith 项目名称。Shell 命令仍使用用户原始的 LANGSMITH_PROJECT 运行,因此应用、测试或脚本跟踪可以出现在单独的项目中。参见使用 LangSmith 跟踪。
string
default:"false"
optional
切换 Deep Agents Code 的 LangSmith 代理跟踪输入和输出的客户端机密编辑。接受 1、true、yes 或 on 以启用编辑,0、false、no 或 off 以禁用(不区分大小写)。当启用编辑时,如果无法配置编辑,则该次运行的跟踪将被禁用。参见配置 LangSmith 跟踪编辑。
string
optional
第二个 LangSmith 项目,也用于写入代理跟踪。设置后且跟踪处于活动状态时,每次代理运行都会双重写入主项目(来自 DEEPAGENTS_CODE_LANGSMITH_PROJECT,或默认为 deepagents-code)和此项目。默认关闭。参见使用 LangSmith 跟踪。
string
optional
设置时禁用自动更新检查。这也会阻止启动时的自动更新安装。
integer
optional
LangGraph 图步骤预算,即 dcode 代理图在每轮中可执行的最大节点调用次数。有效范围:25–100000。超出范围或非整数值将记录警告并回退到默认值(2000)。可通过 CLI 的 --recursion-limit 覆盖。参见代理运行时限制。
string
optional
以逗号分隔的允许的 shell 命令(或 recommended / all)。
string
optional
将用户标识符附加到 LangSmith 跟踪元数据。

使用 dcode doctor 运行诊断

当 Deep Agents Code 无法正常启动、提供商或 MCP 服务器无法连接、跟踪配置错误,或者安装或更新看起来有问题时,请使用 dcode doctor。它会运行诊断而不启动会话,并汇总当前运行时状态。
输出:
当您既需要高级别健康检查又需要特定设置的精确来源时,请将 dcode doctor 与 dcode config show 配合使用。

数据位置

Deep Agents Code 将数据存储在两个目录层次结构中:
  • ~/.deepagents/ — Deep Agents 特有的数据(代理记忆、技能、会话)
  • ~/.agents/ — 工具无关的数据(在 AI CLI 工具之间共享的技能)

目录结构

内容存放位置

优先级规则

当相同项目存在于多个位置时,更高优先级完全胜出(不合并)。

技能

优先级顺序(从低到高):
  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/ — 项目级 (最高)
每个子代理是一个带有 YAML 前置元数据(name、description、可选的 model)和系统提示的 markdown 主体的 AGENTS.md 文件。有关完整格式参考,请参见在 Deep Agents Code 中使用子代理。

指令

所有指令来源合并(不覆盖):
  1. 包内基础提示 (始终加载)
  2. ~/.deepagents/{agent}/AGENTS.md (追加)
  3. .deepagents/AGENTS.md (追加)
  4. 项目根目录下的 AGENTS.md (追加)

.deepagents 与 .agents

对适用于任何 AI 编码助手的技能,使用 .agents/skills/。 对依赖 Deep Agents 特有工具或约定的技能,使用 .deepagents/skills/。

清理

删除 ~/.deepagents/.state/sessions.db 将移除所有对话历史和检查点。除非您有 sessions.db 文件的备份,否则此操作无法撤消。

另请参见