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
# 仅覆盖 CLI 的 OPENAI_API_KEY，不影响其他工具
DEEPAGENTS_CLI_OPENAI_API_KEY=sk-cli-only

# 通过将带前缀的变量设置为空来阻止 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 = "anthropic:claude-sonnet-4-5"   # 上次 /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
提供商具有以下配置选项：
​
models
string[]
可选
一个模型名称列表，用于在此提供商的交互式 /model 切换器中显示。对于已经附带模型配置文件的提供商，您在此添加的任何名称会与捆绑的名称一起出现，这对于尚未添加到包中的新发布模型很有用。对于任意提供商，此列表是切换器中模型的唯一来源。在此列出的模型绕过基于配置文件的过滤条件，始终显示在切换器中。这是在切换器中显示因配置文件缺少 tool_calling 支持或尚不存在而被排除的模型的推荐方式。此键是可选的。无论模型是否出现在切换器中，您始终可以直接将任何模型名称传递给 /model 或 --model；提供商在请求时验证名称。
​
api_key_env
string
可选
覆盖凭证检查的环境变量名称。大多数聊天模型包自动从默认 env var 读取。请参阅提供商参考表，了解每个提供商检查的变量。
​
base_url
string
可选
覆盖提供商使用的 base URL（如果支持）。请参阅提供商包的参考文档了解更多。
​
params
object
可选
转发到模型构造函数的额外关键字参数。扁平键（例如 temperature = 0）应用于此提供商的所有模型。模型键控的子表（例如 [params."gpt-4o"]）仅覆盖该模型的单独值；合并是浅层的（模型在冲突时获胜）。
​
profile
object
可选
（高级）覆盖模型的运行时配置文件中的字段（例如 max_input_tokens）。扁平键应用于此提供商的所有模型。模型键控的子表（例如 [profile."claude-sonnet-4-5"]）仅覆盖该模型的单独值；合并是浅层的（模型在冲突时获胜）。这些覆盖在模型创建后应用，因此对上下文限制显示、自动总结和任何其他读取配置文件的特性都有效。
​
class_path
string
可选
用于任意模型提供商。module.path:ClassName 格式的完全限定 Python 类。设置后，CLI 直接导入并实例化此类作为提供商 <name>。该类必须是 BaseChatModel 子类。
​
enabled
boolean
default:"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} —— 无覆盖，仅提供商级别参数。
合并是浅层的：模型子表中存在的任何键都会替换提供商级别 params 中的相同键，而仅存在于提供商级别的键被保留。

​
使用 --model-params 进行 CLI 覆盖

对于一次性调整而不编辑配置文件，请在启动时或使用 /model 命令的会话中期通过 --model-params 传递 JSON 对象： 
deepagents --model ollama:llama3 --model-params '{"temperature": 0.9, "num_ctx": 16384}'

# 在非交互模式下
deepagents -n "Summarize this repo" --model ollama:llama3 --model-params '{"temperature": 0}'
在 TUI 内部
/model --model-params '{"temperature": 0.9}' ollama:llama3
/model --model-params '{"num_ctx": 16384}'  # 打开选择器，将参数应用到所选模型
这些具有最高优先级，覆盖配置文件 params 中的值。会话中期的参数仅应用于当前会话，不会持久化。--model-params 不能与 --default 结合使用。

​
配置文件覆盖（高级）

覆盖模型的运行时配置文件中的字段，以更改 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 anthropic:claude-sonnet-4-5 --profile-override '{"max_input_tokens": 4096}'

# 在非交互模式下
deepagents -n "Summarize this repo" --profile-override '{"max_input_tokens": 4096}'
这些在配置文件覆盖之上合并（CLI 获胜）。优先级链为：模型默认值 < config.toml profile < CLI --profile-override。 --profile-override 值在会话中期的 /model 热切换中保持不变 —— 切换模型会将覆盖重新应用到新模型。

​
自定义 base 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

​
任意提供商

您可以使用 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 不知道，请在提供商配置文件中声明：
[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 中提供模型配置文件，而不是在 models 键下定义它们。请参阅 LangChain 模型配置文件了解更多。

​
技能额外允许目录

默认情况下，当 CLI 加载技能时，它会验证解析后的技能文件路径保持在标准技能目录之一内。这可以防止技能目录内的符号链接读取这些根目录之外的任意文件。 如果您将共享技能资产存储在非标准位置，并使用标准技能目录中的符号链接来引用它们，您可以将该位置添加到包含允许列表中。这不会添加新的技能发现位置：技能仍然仅从标准目录中发现。
​
extra_allowed_dirs
string[]
可选
添加到技能包含允许列表的路径。支持 ~ 展开。
[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 可以自动检查和安装更新。 
[update]
auto_update = true
环境变量优先于配置文件。 启用后，CLI 在会话开始时检查 PyPI 是否有更新版本，并使用检测到的安装方法（uv、Homebrew 或 pip）自动升级。禁用时（默认），CLI 会显示更新提示和适当的安装命令。 您也可以随时使用 /update 斜杠命令手动检查和安装更新，这会绕过缓存并内联报告成功或失败。 升级后，CLI 在下次启动时显示”新增功能”横幅，并附有更新日志链接。 在会话退出时，如果会话期间检测到更新版本，则显示更新横幅作为提醒。

​
托管部署

安装脚本 支持以 root 身份运行，面向 macOS MDM 工具（Kandji、Jamf 等），这些工具在最小的 root 环境中执行脚本。 当 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
string
可选
启用自动 CLI 更新（1、true 或 yes）。
​
DEEPAGENTS_CLI_DEBUG
string
可选
启用详细调试日志记录到文件。
​
DEEPAGENTS_CLI_DEBUG_FILE
string
default:"/tmp/deepagents_debug.log"
可选
调试日志文件路径。
​
DEEPAGENTS_CLI_EXTRA_SKILLS_DIRS
string
可选
添加到技能包含允许列表的冒号分隔路径。
​
DEEPAGENTS_CLI_LANGSMITH_PROJECT
string
可选
覆盖 Agent 跟踪的 LangSmith 项目名称。请参阅使用 LangSmith 进行跟踪。
​
DEEPAGENTS_CLI_NO_UPDATE_CHECK
string
可选
设置时禁用自动更新检查。
​
DEEPAGENTS_CLI_SHELL_ALLOW_LIST
string
可选
允许的逗号分隔 shell 命令（或 recommended / all）。
​
DEEPAGENTS_CLI_USER_ID
string
可选
将用户标识符附加到 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 编辑器，CLI 在启动编辑器后等待，确保在您保存并关闭文件之前不会继续。
如果您更喜欢使用终端内编辑器，可以禁用外部编辑器功能。