跳到主要内容

文档索引

在以下地址获取完整的文档索引：https://docs.langchain.org.cn/llms.txt

在进一步探索之前，请使用此文件发现所有可用页面。

CLI 将其配置存储在 ~/.deepagents/ 目录中。主要的配置文件包括：
文件格式目的
config.tomlTOML模型默认值、提供商设置、构造函数参数、配置文件覆盖、主题、更新设置、MCP 信任库
.envDotenv全局 API 密钥和机密信息
hooks.jsonJSON外部工具对 CLI 生命周期事件的订阅
.mcp.jsonJSON全局 MCP 服务器定义

​
环境变量

CLI 从 dotenv 文件加载环境变量，因此您无需在 shell 配置文件中执行 export API 密钥，也无需在不同项目中重复创建 .env 文件。

​
加载顺序和优先级

启动时会加载两个 .env 文件：
  1. 项目 .env — 当前工作目录中的 .env 文件（如果存在）
  2. 全局 ~/.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
# Override OPENAI_API_KEY only for the CLI, without affecting other tools
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only

# Block a shell-exported key within the CLI by setting the prefixed var to empty
DEEPAGENTS_CLI_ANTHROPIC_API_KEY=
在执行 /reload 时，CLI 会重新读取 .env 文件并获取带前缀的值，因此您可以在不重启的情况下轮换密钥。

​
示例

在 ~/.deepagents/.env 中存储一次 API 密钥 
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
LANGSMITH_API_KEY=lsv2_...
TAVILY_API_KEY=tvly-...

# If OPENAI_API_KEY is already exported in your shell for other tools,
# use the prefix to give the CLI its own key without conflict
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only-...
然后在需要时，通过在项目目录中放置 .env 文件来进行逐项目覆盖。

​
配置文件

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

​
默认模型和最近模型

[models]
default = "ollama:qwen3:4b"             # your intentional long-term preference
recent = "google_genai:gemini-3.1-pro-preview"   # last /model switch (written automatically)
[models].default 的优先级始终高于 [models].recent。/model 命令仅写入 [models].recent，因此您配置的默认值永远不会被会话中的切换操作覆盖。要移除默认值，请使用 /model --default --clear 或从配置文件中删除 default 键。

​
最近的智能体

[agents]
recent = "backend-dev"   # last /agents switch (written automatically)
通过 /agents 斜杠命令选择智能体会将名称写入 [agents].recent。下次直接启动 deepagents 时会自动恢复该智能体。显式的 -a/--agent 始终具有最高优先级，而 -r/--resume 会绕过最近记录，从而恢复线程原始的智能体。请参阅 切换智能体 了解完整的优先级链。

​
提供商配置

每个提供商都是 [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
提供商具有以下配置选项
​
models
字符串[]
可选
在此提供商的交互式 /model 切换器中显示的模型名称列表。对于已经附带模型 profile 的提供商，您在此处添加的任何名称都会与内置名称并列显示，这对于尚未添加到包中的新发布模型非常有用。对于 任意提供商，此列表是切换器中模型的唯一来源。此处列出的模型将 绕过 基于 profile 的 过滤标准，并始终出现在切换器中。这使得它成为显示那些因 profile 缺少 tool_calling 支持或尚不存在而被排除的模型的推荐方式。此键是可选的。无论模型是否出现在切换器中，您始终可以直接将任何模型名称传递给 /model 或 --model；提供商会在请求时验证名称。
​
api_key_env
字符串
可选
保存 API 密钥的环境变量的 名称（例如 "OPENAI_API_KEY"），而不是密钥本身。CLI 在启动时从该环境变量读取凭据，以便在创建模型前验证访问权限。大多数聊天模型包会自动从默认环境变量中读取。请参阅 提供商参考 表以了解每个提供商检查的具体变量。
​
base_url
字符串
可选
覆盖提供商使用的基础 URL（如果支持）。有关更多信息，请参考您的提供商软件包的 参考文档。
​
params
对象
可选
转发给模型构造函数的额外关键字参数。扁平键（例如 temperature = 0）适用于此提供商的每个模型。以模型为键的子表（例如 [params."gpt-4o"]）仅覆盖该模型的单个值；合并是浅层的（发生冲突时以模型配置为准）。请勿将凭据（例如 api_key）放在 params 中。请使用 api_key_env 指向环境变量。
​
profile
对象
可选
（高级）覆盖模型运行时 profile 中的字段（例如 max_input_tokens）。扁平键适用于此提供商的每个模型。以模型为键的子表（例如 [profile."claude-sonnet-4-5"]）仅覆盖该模型的单个值；合并是浅层的（发生冲突时以模型配置为准）。这些覆盖在模型创建后应用，因此它们会对上下文限制显示、自动摘要以及任何其他读取 profile 的功能生效。
​
class_path
字符串
可选
用于 任意模型 提供商。格式为 module.path:ClassName 的完整限定 Python 类。设置后，CLI 会直接导入并实例化此类作为提供商 <name>。该类必须是 BaseChatModel 的子类。
​
enabled
布尔值
默认值："true"
可选
此提供商是否出现在 /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-params 或在会话中使用 /model 传递 JSON 对象。CLI 标志的优先级高于配置文件。有关语法和提供商特定示例，请参阅提供商页面上的 模型参数。

​
Profile 覆盖（高级）

覆盖模型运行时 profile 中的字段，以更改 CLI 对模型能力的理解。最常见的用例是降低 max_input_tokens 以更早触发自动摘要 — 这对于测试或限制上下文使用非常有用 
# Apply to all models from this provider
[models.providers.anthropic.profile]
max_input_tokens = 4096
逐模型子表的工作方式与 params 相同 — 冲突时模型级别的值优先 
[models.providers.anthropic.profile]
max_input_tokens = 4096

# This model gets a higher limit
[models.providers.anthropic.profile."claude-sonnet-4-5"]
max_input_tokens = 8192
Profile 覆盖在模型创建后合并到模型的 profile 中。任何读取 profile 的功能（状态栏中的上下文限制显示、自动摘要阈值、能力检查）都将看到覆盖后的值。

​
使用 --profile-override 进行 CLI profile 覆盖（高级）

要在运行时覆盖模型 profile 字段而无需编辑配置文件，请通过 --profile-override 传递 JSON 对象 
deepagents --profile-override '{"max_input_tokens": 4096}'

# Combine with --model
deepagents --model google_genai:gemini-3.1-pro-preview --profile-override '{"max_input_tokens": 4096}'

# In non-interactive mode
deepagents -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'
这些值将合并在配置文件 profile 覆盖之上（CLI 优先）。优先级链为：模型默认值 < config.toml profile < CLI --profile-override。 --profile-override 值在会话中执行 /model 热切换时依然有效 — 切换模型会将覆盖重新应用于新模型。

​
自定义基础 URL

某些提供商软件包接受 base_url 来覆盖默认端点。例如，langchain-ollama 通过底层的 ollama 客户端默认指向 https://: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）不绑定模型 profile 数据（请参阅 提供商参考 获取完整列表）。在这种情况下，交互式 /model 切换器将不会列出该提供商的模型。您可以通过在配置文件中为该提供商定义 models 列表来填补这一空白 
[models.providers.ollama]
models = ["llama3", "mistral", "codellama"]
/model 切换器现在将包含一个列出这些模型的 Ollama 部分。 这完全是可选的。您始终可以通过直接指定完整名称来切换到任何模型：
/model ollama:llama3

​
任意提供商

您可以使用 class_path 使用任何 LangChain BaseChatModel 子类。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 并不知情，请在提供商 profile 中声明它
[models.providers.xyz.profile]
tool_calling = true
max_input_tokens = 128000
将 max_input_tokens 设置为模型支持的值，以启用准确的上下文长度追踪和自动摘要。
提供商软件包必须安装在与 deepagents-cli 相同的 Python 环境中 
# If deepagents-cli was installed with uv tool:
uv tool install deepagents-cli --with my_package
当您切换到 my_custom:my-model-v1（通过 /model 或 --model）时，模型名称 (my-model-v1) 将作为 model 关键字参数传递 
MyChatModel(model="my-model-v1", base_url="...", api_key="...", temperature=0, max_tokens=4096)
class_path 会执行配置文件中任意的 Python 代码。这与 pyproject.toml 构建脚本具有相同的信任模型 — 您控制自己的机器。
您的提供商软件包可以选择在 <package>.data._profiles 的 _PROFILES 字典中提供模型 profile，而不是在 models 键下定义它们。有关更多信息，请参阅 LangChain 模型 profiles。

​
技能额外允许目录

默认情况下，当 CLI 加载技能时，它会验证解析后的技能文件路径是否位于标准 技能目录 内。这可以防止技能目录内的符号链接读取这些根目录之外的任意文件。 如果您将共享技能资产存储在非标准位置，并使用标准技能目录中的符号链接来引用它们，则可以将该位置添加到包含白名单中。这 不会 增加新的技能发现位置：技能仍然仅能从标准目录中被发现。
​
extra_allowed_dirs
字符串[]
可选
添加到技能包含白名单的路径。支持 ~ 扩展。
[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 (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 后生效。

​
自动更新

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

​
托管部署

安装脚本 支持以 root 身份运行，针对在极简 root 环境中执行脚本的 macOS MDM 工具（Kandji、Jamf 等）。 当 id -u 为 0 时，脚本会：
  1. 解析真实控制台用户的 HOME（通过 /dev/console 或 /Users 目录扫描）
  2. 在每个安装步骤后，将所有创建的文件通过 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_ 前缀 了解该前缀如何作为第三方凭据的覆盖机制。
​
DEEPAGENTS_CLI_AUTO_UPDATE
字符串
可选
启用 CLI 自动更新（1, true, 或 yes）。
​
DEEPAGENTS_CLI_DEBUG
字符串
可选
启用详细的调试日志到文件。接受 1, true, yes, on（不区分大小写）作为启用；0, false, no, off, 空字符串或未设置则禁用。启用后，每个会话的服务端日志文件在关机时会被保留，其路径将打印到 stderr 以供排查。
​
DEEPAGENTS_CLI_DEBUG_FILE
字符串
默认值："/tmp/deepagents_debug.log"
可选
调试日志文件的路径。
​
DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS
字符串
可选
添加到 技能包含白名单 的以冒号分隔的路径。
​
DEEPAGENTS_CLI_LANGSMITH_PROJECT
字符串
可选
覆盖智能体追踪的 LangSmith 项目名称。请参阅 使用 LangSmith 进行追踪。
​
DEEPAGENTS_CLI_NO_UPDATE_CHECK
字符串
可选
设置后禁用自动更新检查。
​
DEEPAGENTS_CLI_SHELL_ALLOW_LIST
字符串
可选
以逗号分隔的允许执行的 shell 命令（或 recommended / all）。
​
DEEPAGENTS_CLI_USER_ID
字符串
可选
向 LangSmith 追踪元数据附加用户标识符。

​
外部编辑器

按 Ctrl+X 或输入 /editor 在外部编辑器中编写提示词。CLI 会依次检查 $VISUAL、$EDITOR，最后回退到 vi (macOS/Linux) 或 notepad (Windows)。图形界面编辑器（VS Code, Cursor, Zed, Sublime Text, Windsurf）会自动接收 --wait 标志，因此 CLI 会阻塞直到您关闭文件。 
# Set in your shell profile (~/.zshrc, ~/.bashrc, etc.)
export VISUAL="code"    # GUI editor (--wait auto-injected)
export EDITOR="nvim"    # Terminal fallback

​
挂钩

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

​
设置

创建 ~/.deepagents/hooks.json 
{
  "hooks": [
    {
      "command": ["bash", "-c", "cat >> ~/deepagents-events.log"],
      "events": ["session.start", "session.end"]
    }
  ]
}
现在，每当会话开始或结束时，CLI 都会将事件载荷追加到 ~/deepagents-events.log 中。

​
钩子 (Hook) 配置

配置文件包含一个 hooks 数组。每个条目包含：
​
命令
list[str]
必填
要运行的命令及其参数。不进行 shell 扩展：如果需要，请使用 ["bash", "-c", "..."]。
​
events
list[str]
可选
要订阅的事件名称。省略或留空以接收 所有 事件。
{
  "hooks": [
    {
      "command": ["python3", "my_handler.py"],
      "events": ["session.start", "task.complete"]
    },
    {
      "command": ["bash", "log_everything.sh"]
    }
  ]
}
上面的第二个钩子没有 events 过滤器，因此它会接收 CLI 发出的每一个事件。

​
载荷格式

每个钩子命令都会在 stdin 上接收到一个 JSON 对象，其中包含一个 "event" 键以及特定于事件的字段 
{
  "event": "session.start",
  "thread_id": "abc123"
}

​
事件参考

​
session.start

在智能体会话开始时触发（包括交互式和非交互式模式）。
​
thread_id
字符串
必填
会话线程标识符。

​
session.end

在会话退出时触发。
​
thread_id
字符串
必填
会话线程标识符。

​
user.prompt

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

​
input.required

当智能体需要人类输入时触发（人类在环中断）。 无额外字段。

​
permission.request

在一个或多个工具调用需要用户许可的确认对话框之前触发。
​
tool_names
list[str]
必填
请求许可的工具名称。

​
tool.error

当工具调用返回错误时触发。
​
tool_names
list[str]
必填
发生错误的工具名称。

​
task.complete

当智能体完成当前任务时触发（流式循环结束且没有进一步中断）。
​
thread_id
字符串
必填
会话线程标识符。

​
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": []
    }
  ]
}

{
  "hooks": [
    {
      "command": [
        "bash", "-c",
        "osascript -e 'display notification \"Agent finished\" with title \"Deep Agents\"'"
      ],
      "events": ["task.complete"]
    }
  ]
}
编写一个从 stdin 读取 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 流向 stdin，绝不会作为命令行参数。json.dumps 处理了转义。
  • 默认无 shell：命令运行时 shell=False，防止 shell 注入。
  • 格式错误的配置：无效的 JSON 或意外类型会产生记录警告，而不是安全问题。
仅添加来自您信任源的钩子。钩子具有与您的用户帐户相同的权限。
将这些文档连接到 Claude、VSCode 等，以获得实时答案。
在 GitHub 上编辑此页面 或 提交问题。
© . This site is unofficial and not affiliated with LangChain, Inc.