LangChain 中文文档

外观

Deep Agents Code 把配置存储在 ~/.deepagents/ 以及项目级 dotfile 中。完整的目录树、会话存储与技能路径参见 数据位置。

主要配置文件包括：

  • 配置文件 — 编辑 config.toml 以设置模型默认值、提供商设置、主题与更新设置。
  • 环境变量 — 在 ~/.deepagents/.env 或 shell 导出中设置全局 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 导出总是胜过 .env 值。参见 加载顺序与优先级。

提供商端点（base_url）与其匹配的 API 密钥一起解析。参见 端点、密钥与网关。

检查配置 ​

dcode config 命令组会在不启动会话的情况下报告当前生效的配置以及每个值的来源。这对于确认某个环境变量或 config.toml 设置是否被读取很有用，也便于在 bug 报告中分享脱敏后的快照。

命令说明
dcode config show对照实时环境与 config.toml 解析每个选项，打印有效值及其来源
dcode config list（别名 ls）列出每个可用选项及其类型、默认值、可在何处设置，但不解析值
dcode config get <key>显示单个选项的有效值与来源，例如 dcode config get interpreter.memory_limit_mb
dcode config path显示磁盘上配置文件的位置（config.toml、项目与全局 .env、hooks.json 以及受管状态文件）以及它们各自是否存在

这四个命令都接受 --json 以输出机器可读的结果。管理子命令的完整列表参见 CLI 参考。

WARNING

提供商凭据及其他机密只会被报告为“已配置 / 未配置”——config show 或 config get 永远不会打印它们的值，因此输出可以安全地粘贴到 bug 报告中。

环境变量 ​

除了 shell 导出之外，Deep Agents Code 还会从 dotenv 文件读取环境变量，因此你可以把 API 密钥留在 shell 配置文件之外，并避免在多个项目间重复 .env 文件。

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

具体到提供商密钥，参见 提供商凭据。

加载顺序与优先级 ​

启动时，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}：

bash
# 为 Deep Agents Code 提供它自己的值，不影响其他工具
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-cli-only

# 或者将其设为空，使 Deep Agents Code 忽略你在 shell 中导出的密钥
DEEPAGENTS_CODE_ANTHROPIC_API_KEY=

技能目录允许列表 ​

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

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

  • extra_allowed_dirs (string[])：添加到技能包含性允许列表的路径。支持 ~ 展开。 toml [skills] extra_allowed_dirs = [ "~/shared-skills", "/opt/team-skills", ]

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

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

设置环境变量时，它优先于配置文件的值。修改在 /reload 时生效。

主题 ​

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

Deep Agents Code 内置了许多主题。默认主题是 langchain，一个使用 LangChain 品牌配色的深色主题。所选主题持久化在 [ui] 下：

toml
[ui]
theme = "langchain-dark"

关于用户自定义主题、内置覆盖以及终端专属映射，参见 配置文件 中的 [themes.*] 与 [ui.terminal_themes] 节，或直接在 config.toml 中配置：

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

### 用户自定义主题

在 `config.toml` 的 `[themes.<name>]` 节下定义自定义主题。每个节都需要 `label`（str）。`dark`（bool）省略时默认为 `false`——深色主题请设为 `true`。所有颜色字段都是可选的——省略的字段会根据 `dark` 标志回退到内置的深色或浅色调色板。
toml
[themes.my-solarized]
label = "My Solarized"
dark = true
primary = "#268BD2"
warning = "#B58900"

# 带空格的主题名称需要用 TOML 引号括起来
[themes."ocean breeze"]
label = "Ocean Breeze"
primary = "#0077B6"
background = "#CAF0F8"
用户自定义主题会与内置主题一起出现在 `/theme` 选择器中。

### 覆盖内置主题颜色

要微调某个内置主题的颜色而不创建新主题，请使用 `[themes.<builtin-name>]` 节。只有颜色字段会被读取——`label` 与 `dark` 继承自内置主题：
toml
[themes.langchain]
primary = "#FF5500"
省略的颜色字段保留现有的内置值。`[themes.*]` 节的修改在 `/reload` 时生效。

### 将主题映射到终端

如果你在配色方案不同的终端之间切换（例如深色的 iTerm 与浅色的 Apple Terminal），可以在 `[ui.terminal_themes]` 下把每个终端映射到一个主题。Deep Agents Code 匹配 shell 的 `TERM_PROGRAM` 并自动应用映射的主题：
toml
[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 默认会自动检查并安装更新。

选择退出自动更新：

配置文件 ​

toml
[update]
auto_update = false

环境变量 ​

bash
export DEEPAGENTS_CODE_AUTO_UPDATE=0

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

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

要完全抑制自动更新检查：

配置文件 ​

toml
[update]
check = false

环境变量 ​

bash
export DEEPAGENTS_CODE_NO_UPDATE_CHECK=1

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

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

升级后，Deep Agents Code 会在下次启动时显示一个带更新日志链接的“新功能（what's new）”横幅。

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

卸载 ​

要移除 dcode 与 deepagents-code 可执行文件以及隔离的工具环境，运行：

bash
uv tool uninstall deepagents-code

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

bash
rm -rf ~/.deepagents

受管部署 ​

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

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

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

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

用环境变量固定安装 ​

安装脚本会读取一些环境变量，让你可以固定版本、选择附加项并选择全局的 Python 版本。在与管道安装相同的命令行上设置它们：

bash
# 固定精确版本，以实现跨整个设备群的可复现安装
curl -LsSf https://langch.in/dcode | DEEPAGENTS_CODE_VERSION="0.1.16" bash

  • DEEPAGENTS_CODE_VERSION (string)：要安装的确切包版本，例如 0.1.0（或诸如 0.1.0rc1 的预发布版本）。与 DEEPAGENTS_CODE_PRERELEASE 互斥——两者都设置会报错，因为精确固定已经选择了单个版本。

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

  • DEEPAGENTS_CODE_EXTRAS (string)：要安装的以逗号分隔的 pip 附加项，例如 ollama、ollama,groq 或 daytona。可用附加项参见 pyproject.toml。

  • DEEPAGENTS_CODE_PYTHON (string)（默认：3.13）：安装时使用的 Python 版本。

  • DEEPAGENTS_CODE_SKIP_OPTIONAL (string)：设置为 1 以跳过可选工具检查。

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

  • UV_BIN (string)：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。

要把每个用户的模型流量路由到受管网关（在全局配置网关密钥与 base URL），参见 受管网关。

环境变量参考 ​

所有 Deep Agents Code 专属的环境变量都使用 DEEPAGENTS_CODE_ 前缀。该前缀如何同时用作第三方凭据的覆盖机制参见 DEEPAGENTS_CODE_ 前缀。

  • DEEPAGENTS_CODE_AUTO_UPDATE (string)：切换 Deep Agents Code 自动更新。默认启用；设置为 0、false、no 或 off 以选择退出。

  • DEEPAGENTS_CODE_DEBUG (string)：启用写入文件的详细调试日志。接受 1、true、yes、on（不区分大小写）为启用；0、false、no、off、空字符串或未设置为禁用。启用时，按会话的服务器日志文件会在关闭时保留，其路径会打印到 stderr 供排查。

  • DEEPAGENTS_CODE_EXPERIMENTAL (string)：选择加入实验性、不稳定的 Deep Agents Code 行为。设置为 1（或任何真值）以启用实验性功能。

  • DEEPAGENTS_CODE_DEBUG_FILE (string)（默认：/tmp/deepagents_debug.log）：调试日志文件的路径。

INFO

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

  • DEEPAGENTS_CODE_DISABLED_PROJECT_MCP_SERVERS (string)：始终按名称拒绝的项目 MCP 服务器名称（逗号分隔）。Deep Agents Code 会把这些名称与 [mcp].disabled_project_servers 合并；拒绝优先于已保存的批准以及 --trust-project-mcp 标志。

  • DEEPAGENTS_CODE_DANGEROUSLY_ENABLE_PROJECT_MCP_SERVERS (string)：按名称预批准任何项目的项目 MCP 服务器名称（逗号分隔）。这是一个进程级的逃生舱：同一服务器名称下不同的项目、命令更改或 URL 更改仍然匹配。设置后，该变量会在进程期间取代已保存的批准。尽可能优先使用项目 MCP 提示中的已保存批准。

  • DEEPAGENTS_CODE_EXTRA_SKILLS_DIRS (string)：添加到技能包含性允许列表的以冒号分隔的路径。

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

  • DEEPAGENTS_CODE_LANGSMITH_REDACT (string)（默认：false）：切换 Deep Agents Code LangSmith 智能体追踪输入与输出的客户端机密脱敏。接受 1、true、yes 或 on 以启用脱敏，0、false、no 或 off 以禁用，不区分大小写。启用脱敏后，如果无法配置脱敏，本次运行的追踪会被禁用。参见 配置 LangSmith 追踪脱敏。

  • DEEPAGENTS_CODE_LANGSMITH_REPLICA_PROJECTS (string)：一个 同时 写入智能体追踪的第二个 LangSmith 项目。设置且追踪处于活动状态时，每次智能体运行都会双写至主项目（来自 DEEPAGENTS_CODE_LANGSMITH_PROJECT，默认 deepagents-code）与此项目。默认关闭。参见 使用 LangSmith 追踪。

  • DEEPAGENTS_CODE_NO_UPDATE_CHECK (string)：设置后禁用自动更新检查。这同时也会阻止启动时的自动更新安装。

  • DEEPAGENTS_CODE_RECURSION_LIMIT (integer)：LangGraph 图步骤预算，即 dcode 智能体图每轮最多可以执行的节点调用次数。有效范围：25–100000。超出范围或非整数值会记录警告并回退到默认值（2000）。CLI 中的 --recursion-limit 会覆盖它。参见 智能体运行时限制。

  • DEEPAGENTS_CODE_SHELL_ALLOW_LIST (string)：允许的 shell 命令（逗号分隔）（或 recommended / all）。

  • DEEPAGENTS_CODE_USER_ID (string)：把用户标识符附加到 LangSmith 追踪元数据。

使用 dcode doctor 运行诊断 ​

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

bash
# 在终端中显示诊断信息
dcode doctor

输出：

txt
  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 show` or `dcode config get <key>` to drill into config details.
       Run `dcode --version` (or `dcode -v`) for dependency versions.

TIP

当你需要同时获得高层健康检查与某个特定设置的精确来源时，把 dcode doctor 与 dcode config show 搭配使用。

数据位置 ​

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

  • ~/.deepagents/ —— Deep Agents 专属数据（智能体记忆、技能、会话）
  • ~/.agents/ —— 工具无关的数据（跨 AI CLI 工具共享的技能）

目录结构 ​

txt
~/.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
└── {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)
│   ├── 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.dbR/WSQLite 检查点数据库
输入历史~/.deepagents/.state/history.jsonlR/WJSON-lines 格式，上下方向键回忆
ChatGPT OAuth token~/.deepagents/.state/chatgpt-auth.jsonR/W支撑 openai_codex 提供商；在你用 ChatGPT 登录时创建并自动刷新。仅你的用户账户可读。
基础指令包的 default_agent_prompt.mdR不可变，随 Deep Agents Code 升级更新
用户自定义~/.deepagents/{agent}/AGENTS.mdR/W追加到基础指令之后
项目指令.deepagents/AGENTS.md 或 AGENTS.mdR若存在则两者都会加载
用户技能~/.deepagents/{agent}/skills/R/W智能体专属技能
共享技能~/.agents/skills/R工具无关、跨 CLI
项目技能.deepagents/skills/ 或 .agents/skills/R项目作用域
自定义子智能体~/.deepagents/{agent}/agents/R/W用户定义的子智能体
项目子智能体.deepagents/agents/R项目定义的子智能体

优先级规则 ​

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

技能 ​

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

  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 frontmatter（name、description、可选的 model）和 Markdown 正文（用于系统提示词）的 AGENTS.md 文件。完整格式参考参见 在 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

使用 .agents/skills/ 存放可与任何 AI 编码助手配合的技能。 使用 .deepagents/skills/ 存放依赖 Deep Agents 专属工具或约定的技能。

清理 ​

需求操作
重置所有数据rm -rf ~/.deepagents
只清除会话rm ~/.deepagents/.state/sessions.db*
清除输入历史rm ~/.deepagents/.state/history.jsonl
清除已存储的 API 密钥rm ~/.deepagents/.state/auth.json
清除 MCP OAuth tokenrm -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 文件的备份，否则此操作无法撤销。

另请参阅 ​