配置 - Docs by LangChain

CLI 将其配置存储在 ~/.deepagents/ 目录中。主要配置文件如下：

文件	格式	用途
`config.toml`	TOML	模型默认值、提供商设置、构造函数参数、配置文件覆盖、主题、更新设置、MCP 信任存储
`.env`	Dotenv	全局 API 密钥和密钥
`hooks.json`	JSON	外部工具对 CLI 生命周期事件的订阅
`.mcp.json`	JSON	全局 MCP 服务器定义

环境变量

CLI 从 dotenv 文件加载环境变量，因此您无需在 shell 配置文件中 export API 密钥，也无需在项目间复制 .env 文件。

加载顺序和优先级

启动时会加载两个 .env 文件：

项目 .env — 当前工作目录中的 .env 文件（如果存在）
全局 ~/.deepagents/.env — 一个作为所有项目后备的共享文件

有效的优先级是：shell 环境 > 项目 .env > 全局 .env。shell 中已设置的值永远不会被覆盖——包括在 /reload 时。

`DEEPAGENTS_CLI_` 前缀

所有 CLI 特定的环境变量都使用 DEEPAGENTS_CLI_ 前缀（例如，DEEPAGENTS_CLI_AUTO_UPDATE、DEEPAGENTS_CLI_DEBUG）。完整列表请参阅 CLI 环境变量参考。该前缀也作为 CLI 读取的任何环境变量（包括第三方凭据）的覆盖机制。CLI 首先检查 DEEPAGENTS_CLI_{NAME}，然后回退到 {NAME}：

~/.deepagents/.env

# 仅为 CLI 覆盖 OPENAI_API_KEY，而不影响其他工具
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only

# 通过将带前缀的变量设置为空来阻止在 CLI 中使用 shell 导出的密钥
DEEPAGENTS_CLI_ANTHROPIC_API_KEY=

在 /reload 时，CLI 会重新读取 .env 文件并获取带前缀的值，因此您可以轮换密钥而无需重启。

示例

将 API 密钥存储一次在 ~/.deepagents/.env 中：

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
LANGSMITH_API_KEY=lsv2_...
TAVILY_API_KEY=tvly-...

# 如果 OPENAI_API_KEY 已在您的 shell 中为其他工具导出，
# 请使用前缀为 CLI 提供自己的密钥，避免冲突
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only-...

然后根据需要在项目目录中放置 .env 文件来覆盖每个项目。

配置文件

~/.deepagents/config.toml 允许您自定义模型提供商、设置默认值，并向模型构造函数传递额外参数。

默认和最近使用的模型

[models]
default = "ollama:qwen3:4b"             # 您有意的长期偏好
recent = "google_genai:gemini-3.1-pro-preview"   # 上次 /model 切换（自动写入）

[models].default 始终优先于 [models].recent。/model 命令仅写入 [models].recent，因此您配置的默认值永远不会被会话中的切换覆盖。要删除默认值，请使用 /model --default --clear 或从配置文件中删除 default 键。

提供商配置

每个提供商是 [models.providers] 下的一个 TOML 表：

[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

提供商具有以下配置选项：

string[]

optional

要在此提供商的交互式 /model 切换器中显示的模型名称列表。对于已附带模型配置文件的提供商，您在此处添加的任何名称将与捆绑的名称一起显示，这对于尚未添加到包中的新发布的模型很有用。对于任意提供商，此列表是切换器中模型的唯一来源。此处列出的模型绕过基于配置文件的过滤标准，并始终出现在切换器中。这使其成为显示因配置文件缺少 tool_calling 支持或尚不存在而被排除的模型的推荐方式。此键是可选的。您始终可以将任何模型名称直接传递给 /model 或 --model，无论它是否出现在切换器中；提供商在请求时验证名称。

string

optional

保存 API 密钥的环境变量的名称（例如，"OPENAI_API_KEY"），而不是密钥本身。CLI 在启动时从该环境变量读取凭据，以在创建模型之前验证访问权限。大多数聊天模型包会自动从默认环境变量读取。每个提供商检查哪个变量，请参阅提供商参考表。

string

optional

覆盖提供商使用的基础 URL（如果支持）。有关更多信息，请参阅您的提供商包的参考文档。

object

optional

转发给模型构造函数的额外关键字参数。扁平键（例如，temperature = 0）适用于此提供商的所有模型。模型键控的子表（例如，[params."gpt-4o"]）仅覆盖该模型的单个值；合并是浅层的（模型在冲突时获胜）。不要在 params 中放置凭据（例如，api_key）。请改用 api_key_env 指向环境变量。

object

optional

（高级）覆盖模型运行时配置文件中的字段（例如，max_input_tokens）。扁平键适用于此提供商的所有模型。模型键控的子表（例如，[profile."claude-sonnet-4-5"]）仅覆盖该模型的单个值；合并是浅层的（模型在冲突时获胜）。这些覆盖在模型创建后应用，因此它们对上下文限制显示、自动摘要和读取配置文件的任何其他功能生效。

string

optional

用于任意模型提供商。module.path:ClassName 格式的完全限定 Python 类。设置后，CLI 将直接导入并实例化此类作为提供商 <name>。该类必须是 BaseChatModel 子类。

boolean

default:"true"

optional

此提供商是否出现在 /model 选择器中。设置为 false 以隐藏从已安装包自动发现的提供商（例如，您不希望其干扰切换器的传递依赖项）。您仍然可以通过 /model provider:model 或 --model 直接使用已禁用的提供商。

模型构造函数参数

任何提供商都可以使用 params 表向模型构造函数传递额外参数：

[models.providers.ollama.params]
temperature = 0
num_ctx = 8192

每个模型的覆盖

如果特定模型需要不同的参数，请在 params 下添加一个模型键控的子表，以覆盖单个值，而无需复制整个提供商配置：

[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} — 模型覆盖获胜。
ollama:llama3 获得 {temperature: 0, num_ctx: 8192} — 无覆盖，仅提供商级参数。

合并是浅层的：模型子表中存在的任何键都会替换提供商级参数中的相同键，而仅在提供商级的键则被保留。

对于无需编辑 config.toml 的一次性调整，请在启动时或会话中通过 /model 使用 --model-params 传递 JSON 对象。CLI 标志优先级高于配置文件。语法和提供商特定示例请参阅提供商页面上的模型参数。

配置文件覆盖（高级）

覆盖模型运行时配置文件中的字段，以更改 CLI 解释模型功能的方式。最常见的用例是降低 max_input_tokens 以更早触发自动摘要——这对于测试或限制上下文使用很有用：

# 应用于此提供商的所有模型
[models.providers.anthropic.profile]
max_input_tokens = 4096

每个模型的子表与 params 的工作方式相同——模型级值在冲突时获胜：

[models.providers.anthropic.profile]
max_input_tokens = 4096

# 此模型获得更高的限制
[models.providers.anthropic.profile."claude-sonnet-4-5"]
max_input_tokens = 8192

配置文件覆盖在创建后合并到模型的配置文件中。读取配置文件的任何功能——状态栏中的上下文限制显示、自动摘要阈值、功能检查——都将看到覆盖后的值。

使用 `--profile-override` 的 CLI 配置文件覆盖（高级）

要在运行时覆盖模型配置文件字段而无需编辑配置文件，请通过 --profile-override 传递 JSON 对象：

deepagents --profile-override '{"max_input_tokens": 4096}'

# 与 --model 结合使用
deepagents --model google_genai:gemini-3.1-pro-preview --profile-override '{"max_input_tokens": 4096}'

# 在非交互模式下
deepagents -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'

这些会合并到配置文件配置文件覆盖之上（CLI 获胜）。优先级链是：模型默认值 < config.toml 配置文件 < CLI --profile-override。 --profile-override 值在会话中的 /model 热交换中持续存在——切换模型会将覆盖重新应用于新模型。

自定义基础 URL

一些提供商包接受 base_url 来覆盖默认端点。例如，langchain-ollama 通过底层 ollama 客户端默认为 http://localhost:11434。要将其指向其他位置，请在配置中设置 base_url：

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

有关兼容性信息和额外注意事项，请参阅您的提供商的参考文档。

兼容 API

对于公开与 OpenAI 或 Anthropic 线路兼容的 API 的提供商，您可以通过将 base_url 指向提供商的端点来使用现有的 langchain-openai 或 langchain-anthropic 包：

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

提供商在官方规范之上添加的任何功能都不会被捕获。如果提供商提供专用的 LangChain 集成包，请优先使用该包。

将模型添加到交互式切换器

一些提供商（例如 langchain-ollama）不捆绑模型配置文件数据（完整列表请参阅提供商参考）。在这种情况下，交互式 /model 切换器不会列出该提供商的模型。您可以通过在配置文件中为提供商定义 models 列表来填补空白：

[models.providers.ollama]
models = ["llama3", "mistral", "codellama"]

/model 切换器现在将包含一个 Ollama 部分，其中列出了这些模型。这完全是可选的。您始终可以通过直接指定完整名称来切换到任何模型：

/model ollama:llama3

任意提供商

您可以使用任何 LangChain BaseChatModel 子类，使用 class_path。CLI 直接导入并实例化该类——无需内置提供商包。

[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 是可选的。class_path 提供商应内部处理自己的身份验证——当您的模型使用自定义身份验证（JWT 令牌、专有头、mTLS 等）而不是标准 API 密钥时很有用：

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

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

使用此配置，通过 /model xyz:abc-xyz-1 或 --model xyz:abc-xyz-1 切换到该模型。

Deep Agents CLI 需要 tool calling 支持。如果您的自定义模型支持工具调用但 CLI 不知道，请在提供商配置文件中声明它：

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

将 max_input_tokens 设置为您的模型支持的值，以启用准确的上下文长度跟踪和自动摘要。

提供商包必须与 deepagents-cli 安装在相同的 Python 环境中：

# 如果 deepagents-cli 是使用 uv tool 安装的：
uv tool install deepagents-cli --with my_package

当您切换到 my_custom:my-model-v1（通过 /model 或 --model）时，模型名称（my-model-v1）作为 model kwarg 传递：

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

class_path 从您的配置文件中执行任意 Python 代码。这与 pyproject.toml 构建脚本具有相同的信任模型——您控制自己的机器。

您的提供商包可以选择在 <package>.data._profiles 中的 _PROFILES 字典中提供模型配置文件，而不是在 models 键下定义它们。更多信息请参阅 LangChain 模型配置文件。

技能额外允许目录

默认情况下，当 CLI 加载技能时，它会验证解析后的技能文件路径是否位于标准技能目录之一内。这可以防止技能目录内的符号链接读取这些根目录之外的任意文件。如果您将共享技能资产存储在非标准位置，并使用来自标准技能目录的符号链接来引用它们，则可以将该位置添加到包含允许列表中。这不会添加新的技能发现位置：技能仍然仅从标准目录中发现。

string[]

optional

添加到技能包含允许列表的路径。支持 ~ 扩展。

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

或者，将 DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS 环境变量设置为冒号分隔的列表：

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

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

主题

使用 /theme 打开交互式主题选择器。导航列表以实时预览主题，按 Enter 将您的选择持久化到 config.toml。 CLI 附带许多内置主题。默认主题是 langchain，一个带有 LangChain 品牌颜色的深色主题。所选主题持久化在 [ui] 下：

[ui]
theme = "langchain-dark"

用户定义的主题

在 config.toml 的 [themes.<name>] 部分下定义自定义主题。每个部分需要 label（字符串）。dark（布尔值）如果省略则默认为 false——对于深色主题设置为 true。所有颜色字段都是可选的——省略的字段根据 dark 标志回退到内置的深色或浅色调色板。

[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 从内置继承：

[themes.langchain]
primary = "#FF5500"

省略的颜色字段保留现有的内置值。对 [themes.*] 部分的更改在 /reload 时生效。

自动更新

CLI 可以自动检查并安装更新。

配置文件
环境变量

toml [update] auto_update = true

bash export DEEPAGENTS_CLI_AUTO_UPDATE=1

环境变量优先于配置文件。启用后，CLI 在会话开始时检查 PyPI 是否有更新版本，并使用检测到的安装方法（uv、Homebrew 或 pip）自动升级。禁用时（默认），CLI 会显示一个更新提示及相应的安装命令。您也可以随时使用 /update 斜杠命令手动检查并安装更新，该命令会绕过缓存并内联报告成功或失败。升级后，CLI 在下次启动时显示“更新内容”横幅，并附有指向更新日志的链接。在会话退出时，如果在会话期间检测到更新版本，将显示更新横幅作为提醒。

托管部署

安装脚本支持以 root 身份运行，针对在最小 root 环境中执行脚本的 macOS MDM 工具（Kandji、Jamf 等）。当 id -u 为 0 时，脚本：

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

非 root 安装不受影响：所有 root 特定的代码路径在未以 root 身份运行时会短路。要为托管安装预配置自动更新，请在用户的 shell 配置文件中设置 DEEPAGENTS_CLI_AUTO_UPDATE=1，或将包含 [update] auto_update = true 的 config.toml 部署到 ~/.deepagents/config.toml。要完全禁用自动更新和更新检查，请设置 DEEPAGENTS_CLI_NO_UPDATE_CHECK=1。

CLI 环境变量参考

所有 CLI 特定的环境变量都使用 DEEPAGENTS_CLI_ 前缀。前缀如何作为第三方凭据的覆盖机制，请参阅 DEEPAGENTS_CLI_ 前缀。

string

optional

启用自动 CLI 更新（1、true 或 yes）。

string

optional

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

string

default:"/tmp/deepagents_debug.log"

optional

调试日志文件的路径。

string

optional

添加到技能包含允许列表的冒号分隔路径。

string

optional

覆盖代理跟踪的 LangSmith 项目名称。请参阅使用 LangSmith 进行跟踪。

string

optional

设置时禁用自动更新检查。

string

optional

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

string

optional

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

外部编辑器

按 Ctrl+X 或输入 /editor 以在外部编辑器中编写提示。CLI 检查 $VISUAL，然后检查 $EDITOR，最后回退到 vi（macOS/Linux）或 notepad（Windows）。GUI 编辑器（VS Code、Cursor、Zed、Sublime Text、Windsurf）会自动接收 --wait 标志，因此 CLI 会阻塞直到您关闭文件。

# 在您的 shell 配置文件中设置（~/.zshrc、~/.bashrc 等）
export VISUAL="code"    # GUI 编辑器（--wait 自动注入）
export EDITOR="nvim"    # 终端后备

钩子

钩子让外部程序对 CLI 生命周期事件做出反应。在 ~/.deepagents/hooks.json 中配置命令，CLI 会在事件触发时将 JSON 有效负载通过管道传输到每个匹配命令的标准输入。钩子在后台线程中以即发即忘的方式运行——它们永远不会阻塞 CLI，失败会被记录而不会中断您的会话。

设置

创建 ~/.deepagents/hooks.json：

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

现在，每次会话开始或结束时，CLI 都会将事件有效负载追加到 ~/deepagents-events.log。

钩子配置

配置文件包含一个 hooks 数组。每个条目具有：

list[str]

required

要运行的命令和参数。无 shell 扩展：如果需要，请使用 ["bash", "-c", "..."]。

list[str]

optional

要订阅的事件名称。省略或留空以接收所有事件。

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

上面的第二个钩子没有 events 过滤器，因此它接收 CLI 发出的每个事件。

有效负载格式

每个钩子命令在标准输入上接收一个 JSON 对象，其中包含 "event" 键和事件特定字段：

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

事件参考

`session.start`

当代理会话开始时触发（交互式和非交互式模式）。

string

required

会话线程标识符。

`session.end`

当会话退出时触发。

string

required

会话线程标识符。

`user.prompt`

在交互模式下，当用户提交聊天消息时触发。无额外字段。

`input.required`

当代理需要人工输入（Human in the Loop断）时触发。无额外字段。

`permission.request`

在一个或多个工具调用需要用户权限时，在批准对话框之前触发。

list[str]

required

请求批准的工具名称。

`tool.error`

当工具调用返回错误时触发。

list[str]

required

出错的工具名称。

`task.complete`

当代理完成其当前任务时触发（流式循环结束，没有进一步的中断）。

string

required

会话线程标识符。

`context.compact`

在 CLI 压缩（摘要）对话上下文之前触发。无额外字段。

执行模型

后台线程：钩子子进程通过 asyncio.to_thread 在线程中运行，因此主事件循环永远不会被阻塞。
并发分派：当多个钩子匹配一个事件时，它们在线程池中并发运行。
5 秒超时：每个命令有 5 秒超时。超过此时间的命令将被终止。
即发即忘：错误按钩子捕获，并在调试/警告级别记录。失败的钩子永远不会崩溃或停滞 CLI。
延迟加载：配置文件在第一次事件分派时读取一次，并在会话的其余时间缓存。
无 shell 扩展：命令直接执行（不通过 shell）。如果需要 shell 功能（如管道或变量扩展），请包装在 ["bash", "-c", "..."] 中。

钩子示例

将所有事件记录到文件

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

任务完成时桌面通知 (macOS)

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

Python 处理程序

编写一个处理程序脚本，从标准输入读取 JSON 有效负载：

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

安全注意事项

钩子遵循与 Git 钩子或 shell 别名相同的信任模型——任何可以写入 ~/.deepagents/hooks.json 的用户都可以执行任意命令。这是设计使然：

无命令注入：有效负载数据仅作为 JSON 流向标准输入，永远不会流向命令行参数。json.dumps 处理转义。
默认无 shell：命令以 shell=False 运行，防止 shell 注入。
格式错误的配置：无效的 JSON 或意外类型会产生记录的警告，而不是安全问题。

仅添加来自您信任来源的钩子。钩子与您的用户帐户具有相同的权限。

将这些文档连接到 Claude、VSCode 等，通过 MCP 获取实时答案。

在 GitHub 上编辑此页面或提交问题。

​环境变量

​加载顺序和优先级

​DEEPAGENTS_CLI_ 前缀

​示例

​配置文件

​默认和最近使用的模型

​最近使用的代理

​提供商配置

​模型构造函数参数

​每个模型的覆盖

​配置文件覆盖（高级）

​使用 --profile-override 的 CLI 配置文件覆盖（高级）

​自定义基础 URL

​兼容 API

​将模型添加到交互式切换器

​任意提供商

​技能额外允许目录

​主题

​用户定义的主题

​覆盖内置主题颜色

​自动更新

​托管部署

​CLI 环境变量参考

​外部编辑器

​钩子

​设置

​钩子配置

​有效负载格式

​事件参考

​session.start

​session.end

​user.prompt

​input.required

​permission.request

​tool.error

​task.complete

​context.compact

​执行模型

​钩子示例

​安全注意事项

环境变量

加载顺序和优先级

`DEEPAGENTS_CLI_` 前缀

示例

配置文件

默认和最近使用的模型

最近使用的代理

提供商配置

模型构造函数参数

每个模型的覆盖

配置文件覆盖（高级）

使用 `--profile-override` 的 CLI 配置文件覆盖（高级）

自定义基础 URL

兼容 API

将模型添加到交互式切换器

任意提供商

技能额外允许目录

主题

用户定义的主题

覆盖内置主题颜色

自动更新

托管部署

CLI 环境变量参考

外部编辑器

钩子

设置

钩子配置

有效负载格式

事件参考

`session.start`

`session.end`

`user.prompt`

`input.required`

`permission.request`

`tool.error`

`task.complete`

`context.compact`

执行模型

钩子示例

安全注意事项