配置 Deep Agents

为什么需要它

你有没有试过在多个项目间切换不同的 LLM Provider？

配置文件总览

所有配置集中在 ~/.deepagents/ 目录下

~/.deepagents/
  config.toml      # 主配置文件：模型、Provider、主题、更新等
  .env             # API 密钥（所有项目共享）
  hooks.json       # 生命周期钩子（响应 Agent 事件）
  .mcp.json        # MCP 服务器定义（全局工具扩展）
  .state/          # 运行时状态（自动管理，不要手动修改）

Provider 凭证

两种方式管理 API 密钥：/auth 命令或环境变量

Deep Agents Code 按以下优先级检查凭证：已存储的密钥 > 环境变量。

# 适用于 CI/CD 或无头模式——密钥在 shell 关闭后失效
export ANTHROPIC_API_KEY="sk-ant-..."
export OPENAI_API_KEY="sk-..."
export DEEPSEEK_API_KEY="sk-..."         # DeepSeek V4 系列（需安装 langchain-deepseek）

环境变量加载

两级 .env 文件 + shell 环境变量，优先级清晰不冲突

# ~/.deepagents/.env — 全局共享密钥（所有项目通用）
ANTHROPIC_API_KEY=sk-ant-...       # Anthropic Claude 系列模型
OPENAI_API_KEY=sk-...              # OpenAI GPT 系列模型
DEEPSEEK_API_KEY=sk-...            # DeepSeek V4 系列（需安装 langchain-deepseek）
LANGSMITH_API_KEY=lsv2_...         # LangSmith 追踪和沙箱
TAVILY_API_KEY=tvly-...            # Tavily 网络搜索工具

TAVILY_API_KEY=tvly-...

# 前缀隔离——仅 Deep Agents Code 读取此密钥，不影响其他工具
DEEPAGENTS_CODE_TAVILY_API_KEY=tvly-...

前缀覆盖机制

DEEPAGENTS_CODE_ 前缀让 Deep Agents 读取独立的密钥值

前缀的核心用途：为 Deep Agents Code 指定独立密钥，不影响其他工具读取同名环境变量。

# ~/.deepagents/.env

# 仅覆盖 Deep Agents Code 使用的 OPENAI_API_KEY，其他工具仍读取原始值
DEEPAGENTS_CODE_OPENAI_API_KEY=sk-cli-only

# 设为空值可屏蔽shell 中导出的密钥，使 Deep Agents Code 无法使用它
DEEPAGENTS_CODE_ANTHROPIC_API_KEY=

默认模型与 Agent

在 config.toml 中设置长期偏好，命令行切换不会覆盖默认值

# ~/.deepagents/config.toml

[models]
default = "ollama:qwen3:4b"                          # 长期偏好
recent = "google-genai:gemini-3.1-pro-preview"       # 最近 /model 切换（自动写入）

[agents]
default = "backend-dev"    # 长期偏好（Ctrl+S 固定）
recent = "frontend-dev"    # 最近 /agents 切换（自动写入）

Provider 配置

每个 Provider 是 [models.providers] 下的一个 TOML 表

[models.providers.<name>]
models = ["gpt-4o"]                   # 切换器中显示的模型
api_key_env = "OPENAI_API_KEY"        # 密钥环境变量名
base_url = "https://api.openai.com/v1"  # 可选：覆盖默认 URL
class_path = "my_package.models:MyChatModel"  # 可选：自定义 Provider
enabled = true                         # 可选：是否在切换器中显示

[models.providers.<name>.params]
temperature = 0          # 适用于此 Provider 的所有模型
max_tokens = 4096

[models.providers.<name>.params."gpt-4o"]
temperature = 0.7        # 仅覆盖 gpt-4o 的 temperature

按模型覆盖参数

在 params 下用模型名为键的子表，覆盖个别值无需复制整个配置

[models.providers.ollama]
models = ["qwen3:4b", "llama3"]  # 在 /model 切换器中显示的模型列表

[models.providers.ollama.params]
temperature = 0       # Provider 级别默认：确定性输出，适合代码生成
num_ctx = 8192        # 上下文窗口大小（token 数）

[models.providers.ollama.params."qwen3:4b"]
temperature = 0.5     # 模型级覆盖：qwen3:4b 用更高 temperature 增加多样性
num_ctx = 4000        # 模型级覆盖：qwen3:4b 使用更小的上下文窗口

Profile 覆盖

高级功能：覆盖模型运行时 Profile，改变 Deep Agents 解读模型能力的方式

最常见的用例是降低 max_input_tokens 以更早触发自动摘要——适用于测试或限制上下文使用量。

# 应用于此 Provider 的所有模型（触发自动摘要的阈值）
[models.providers.anthropic.profile]
max_input_tokens = 4096   # 限制最大输入 token，超出时自动压缩上下文

# 此模型获得更高的限制（模型级覆盖优先）
[models.providers.anthropic.profile."claude-sonnet-4-5"]
max_input_tokens = 8192   # claude-sonnet-4-5 单独放宽到 8192

dcode --profile-override \
  '{"max_input_tokens": 4096}'

# 与 --model 结合
dcode --model google-genai:gemini-3.1-pro \
  --profile-override \
  '{"max_input_tokens": 4096}'

自定义端点

通过 base_url 指向代理、网关或兼容 API

[models.providers.ollama]
base_url = "http://your-host:port"  # 指向局域网或远程 Ollama 实例

[models.providers.openai]
base_url = "https://api.example.com/v1"  # 兼容 OpenAI 的自定义端点
api_key_env = "EXAMPLE_API_KEY"        # 指向存放密钥的环境变量名
models = ["my-model"]                 # 在切换器中显示的模型列表

[models.providers.anthropic]
base_url = "https://api.example.com"  # 兼容 Anthropic 的自定义端点
api_key_env = "EXAMPLE_API_KEY"       # 指向存放密钥的环境变量名
models = ["my-model"]                # 在切换器中显示的模型列表

[models.providers.deepseek]
base_url = "https://api.siliconflow.cn/v1"  # 兼容 DeepSeek 的第三方端点
api_key_env = "DEEPSEEK_API_KEY"             # 密钥环境变量名
models = ["deepseek-v4-pro", "deepseek-v4-flash"]  # V4 系列模型

[models.providers.openai.params]
use_responses_api = false  # 禁用 Responses API，回退到 Chat Completions API

切换器添加模型

某些 Provider 不内置模型 Profile，需要手动配置切换器列表

[models.providers.ollama]
models = ["llama3", "mistral", "codellama"]  # 手动列出模型，绕过 Profile 筛选

配置后，/model 切换器会出现 Ollama 分区并列出这些模型。

自定义 Provider

用 class_path 接入任何 LangChain BaseChatModel 子类

[models.providers.my_custom]
class_path = "my_package.models:MyChatModel"  # 模块路径:类名格式
api_key_env = "MY_API_KEY"                    # 密钥环境变量名（非密钥本身）
base_url = "https://my-endpoint.example.com"  # 自定义 API 端点

[models.providers.my_custom.params]
temperature = 0     # 确定性输出，适合代码生成
max_tokens = 4096   # 最大输出 token 数

MyChatModel(
  model="my-model-v1",     # 自动传入你选择的模型名
  base_url="...",          # 来自 config.toml 的 base_url
  api_key="...",           # 来自 api_key_env 指向的环境变量
  temperature=0,             # 来自 params 配置
  max_tokens=4096            # 来自 params 配置
)

# uv tool 安装方式
uv tool install deepagents-code \
  --with my_package

[models.providers.xyz]
class_path = "abc.integrations.deepagents:DeepAgentsXYZChat"  # 自定义认证类
models = ["abc-xyz-1"]  # 在切换器中显示的模型

[models.providers.xyz.params]
bypass_auth = true   # 跳过标准认证，由自定义类内部处理
temperature = 0

[models.providers.xyz.profile]
tool_calling = true        # 声明模型支持工具调用（必须为 true）
max_input_tokens = 128000  # 最大输入 token 数，用于上下文追踪和自动摘要

Skills 白名单

为 Skill 的符号链接添加额外的允许目录

默认情况下，Deep Agents Code 验证 Skill 文件路径保持在标准 Skill 目录之内，防止符号链接读取任意文件。如果你将共享 Skill 存储在非标准位置：

[skills]
extra_allowed_dirs = [
    "~/shared-skills",     # 家目录下的共享技能（支持 ~ 展开）
    "/opt/team-skills",    # 团队共享的技能目录（绝对路径）
]

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

主题配置

内置主题、自定义主题和终端映射

[ui]
theme = "langchain-dark"  # /theme 选择器按 Enter 后自动写入

[themes.my-solarized]
label = "My Solarized"     # 在 /theme 选择器中显示的名称
dark = true                 # 标记为深色主题
primary = "#268BD2"         # 主色调（蓝色）
warning = "#B58900"         # 警告色（黄色）

[themes."ocean breeze"]
label = "Ocean Breeze"      # 选择器中显示的名称
primary = "#0077B6"         # 主色调（海蓝色）
background = "#CAF0F8"      # 背景色（浅蓝色）

[themes.langchain]
primary = "#FF5500"  # 只覆盖主色调，其他字段保留内置默认值

[ui.terminal_themes]
"Apple_Terminal" = "langchain-light"  # macOS 终端使用浅色主题
"iTerm.app" = "langchain"             # iTerm2 使用默认主题
"vscode" = "langchain-dark"            # VS Code 终端使用深色主题

自动更新

让 Deep Agents Code 自动检查并安装更新

[update]
auto_update = true  # 启用自动更新，会话开始时检查 PyPI 并升级

# 环境变量方式（优先于 config.toml）
export DEEPAGENTS_CODE_AUTO_UPDATE=1

托管部署

以 root 身份运行安装脚本，支持 MDM 工具管理

安装脚本支持以 root 身份运行，适用于在最小化 root 环境中执行脚本的 macOS MDM 工具（Kandji、Jamf 等）。

外部编辑器

按 Ctrl+X 或输入 /editor 在外部编辑器中编写提示

Deep Agents Code 依次检查 $VISUAL、$EDITOR，然后回退到 vi（macOS/Linux）或 notepad（Windows）。

# 在 shell 配置文件中设置（~/.zshrc、~/.bashrc 等）
export VISUAL="code"    # 优先使用 VS Code（GUI 编辑器，自动注入 --wait 阻塞等待）
export EDITOR="nvim"    # VISUAL 不可用时的后备编辑器

Hooks 钩子

让外部程序对 Deep Agents Code 生命周期事件做出响应

在 ~/.deepagents/hooks.json 中配置命令，每当事件触发时，JSON 负载通过管道传递给命令的标准输入。

{
  "hooks": [
    {
      "command": ["bash", "-c", "cat >> ~/deepagents-events.log"],  // 将事件 JSON 追加到日志文件
      "events": ["session.start", "session.end"]  // 仅监听会话开始和结束事件
    }
  ]
}

{
  "event": "session.start",   // 事件名称
  "thread_id": "abc123"      // 会话线程 ID（用于追踪关联事件）
}

Hook 事件

八种生命周期事件，覆盖从会话开始到上下文压缩

{
  "hooks": [{
    "command": ["bash", "-c",
      "jq -c . >> ~/.deepagents/hook-events.jsonl"],  // 用 jq 压缩为单行 JSON 后追加到文件
    "events": []  // 空数组 = 接收所有事件
  }]
}

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

import json, sys
payload = json.load(sys.stdin)  # 从标准输入读取 JSON 负载
event = payload["event"]
if event == "session.start":
    # 将会话 ID 输出到 stderr，避免干扰 stdout 的 Agent 输出
    print(f"Session: {payload['thread_id']}",
          file=sys.stderr)

环境变量速查

所有 DEEPAGENTS_CODE_ 前缀环境变量一览

动手练习

配置一个完整的本地 + 云端混合开发环境

现在轮到你了。根据以下需求，完成 Deep Agents Code 的配置：

需求：
1. 本地使用 Ollama 的 qwen3:4b 作为默认模型
2. 云端备选 google-genai:gemini-3.1-pro-preview
3. Ollama 指向局域网内的 192.168.1.100:11434
4. qwen3:4b 使用 temperature=0.5，其他 Ollama 模型使用 temperature=0
5. 启用 Tavily 网络搜索
6. 任务完成时发送桌面通知
7. 使用 iTerm 时自动应用深色主题

本章回顾

到这里，你已经掌握了 Deep Agents Code 的完整配置体系

延伸阅读