~/.deepagents/ 目录和项目级别的点文件中。有关完整的目录结构、会话存储和技能路径,请参见数据位置。
主要配置文件如下:
配置文件
编辑
config.toml 以设置模型默认值、提供商设置、主题和更新设置。环境变量
在
~/.deepagents/.env 或 shell export 中设置全局 API 密钥和机密。钩子
在
hooks.json 中订阅外部命令到生命周期事件。MCP 服务器
在
~/.deepagents/.mcp.json 中定义全局 MCP 服务器。设置如何解析
Deep Agents Code 会从多个来源合并设置。哪个来源优先取决于设置类型。 常规选项(解释器限制、更新设置、主题以及其他config.toml 键)按以下顺序解析:
- 以
DEEPAGENTS_CODE_为前缀的环境变量 - 标准环境变量(如适用)
~/.deepagents/config.toml- 内置默认值
dcode config show 或 dcode config get <key> 来查看有效值及其来源。参见检查配置。
供应商 API 密钥使用单独的顺序。参见密钥解析顺序。
Dotenv 文件在启动时加载:先加载最近的项目 .env(从启动目录向上遍历),然后是 ~/.deepagents/.env 作为所有项目的全局后备。Shell export 的值始终优先于 .env 值。参见加载顺序和优先级。
供应商端点 (base_url) 与其匹配的 API 密钥一起解析。参见端点、密钥和网关。
检查配置
dcode config 命令组可以报告当前生效的配置以及每个值的来源,而无需启动会话。这对于确认环境变量或 config.toml 设置是否被正确拾取,以及在错误报告中共享经过编辑的快照非常有用。
所有四个命令都接受
--json 参数以获得机器可读的输出。有关管理子命令的完整列表,请参见 CLI 参考。
环境变量
除了 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 中设置它们。
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 值
主题解析顺序
DEEPAGENTS_CODE_THEME环境变量(显式覆盖)。- 当前
TERM_PROGRAM的[ui.terminal_themes]映射。 [ui] theme保存的偏好(通过/theme设置)。- 内置默认值(
langchain)。
自动更新
Deep Agents Code 默认会自动检查并安装更新。 要选择退出自动更新:- 配置文件
- 环境变量
- 配置文件
- 环境变量
/update 斜杠命令手动检查并安装更新,该命令会运行按需检查并内联报告成功或失败。
升级后,Deep Agents Code 会在下次启动时显示一个“新功能”横幅,其中包含指向更新日志的链接。
在会话退出时,如果在会话期间检测到新版本,会显示一个更新横幅作为提醒。
卸载
要删除dcode 和 deepagents-code 二进制文件以及隔离的工具环境,请运行:
~/.deepagents/ 下,包括 config.toml、hooks.json、全局 .env 以及 .state/ 内容(如已保存的会话和凭证)。要同时删除这些数据,请运行:
受管部署
安装脚本支持以 root 身份运行,目标是 macOS MDM 工具(Kandji, Jamf 等),这些工具在最小化的 root 环境中执行脚本。 当id -u 为 0 时,脚本会:
- 通过
/dev/console或扫描/Users目录来解析真实控制台用户的HOME - 在每个安装步骤之后,将所有创建的文件
chown回目标用户
使用环境变量固定安装
安装脚本读取环境变量,让您可以固定版本、选择附加组件并在整个设备群中选择 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 二进制文件的路径。如果未设置,则自动检测。
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
覆盖 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。它会运行诊断而不启动会话,并汇总当前运行时状态。
数据位置
Deep Agents Code 将数据存储在两个目录层次结构中:~/.deepagents/— Deep Agents 特有的数据(代理记忆、技能、会话)~/.agents/— 工具无关的数据(在 AI CLI 工具之间共享的技能)
目录结构
内容存放位置
优先级规则
当相同项目存在于多个位置时,更高优先级完全胜出(不合并)。技能
优先级顺序(从低到高):~/.deepagents/{agent}/skills/— 用户 Deep Agents Code~/.agents/skills/— 用户工具无关.deepagents/skills/— 项目 Deep Agents Code.agents/skills/— 项目工具无关 (最高)
[skills].extra_allowed_dirs。
子代理
优先级顺序(从低到高):~/.deepagents/{agent}/agents/— 用户级.deepagents/agents/— 项目级 (最高)
name、description、可选的 model)和系统提示的 markdown 主体的 AGENTS.md 文件。有关完整格式参考,请参见在 Deep Agents Code 中使用子代理。
指令
所有指令来源合并(不覆盖):- 包内基础提示 (始终加载)
~/.deepagents/{agent}/AGENTS.md(追加).deepagents/AGENTS.md(追加)- 项目根目录下的
AGENTS.md(追加)
.deepagents 与 .agents
清理
另请参见
Connect these docs to Claude, VSCode, and more via MCP for real-time answers.

