Deep Agents Code：定位、安装、配置与凭证

产品定位

Deep Agents Code（dcode）是基于 Python Deep Agents SDK 的开源终端编码 Agent。它不是 TypeScript SDK 的 CLI，也不是只支持某一模型的封装。主要能力包括：

• 跨供应商模型切换。
• 会话 checkpoint、线程恢复与上下文 compact/offload。
• 持久 memory、按需 skills、同步/动态 subagents。
• MCP、plugins、hooks。
• Manual / Auto / YOLO 审批。
• 本地或远程 sandbox 执行。
• LangSmith tracing。

官方安装入口是 curl -LsSf https://langch.in/dcode | bash。安装脚本会管理隔离的 Python/uv 工具环境；Windows 未正式支持，文档只建议尝试 WSL。

日常使用地图

交互模式直接描述任务，Agent 先展示 diff 并在敏感动作前审批。常用命令按职责分组：

/reload 会重新读取项目/全局 .env、配置、skills、plugin skills 和 MCP，保留当前对话。/offload 把历史写入存储并放入摘要占位；需要时 Agent 可再读原文件。

Shell 模式以 ! 进入。Shift+Tab / Ctrl+T 只在 Manual 与 Auto 间切换，不会进入 YOLO。

非交互与自动化

-n 或 stdin pipe 会启动一次性 headless run。每次都是新 thread；memory、skills 与 config 等文件状态仍会保留。

关键安全默认：

• 非交互 shell 默认禁用。
• 用 -S / --shell-allow-list 显式允许命令名、recommended 或 all。
• -S all 允许任意 shell 且无人工确认，风险等同无人值守本地执行。
• --max-turns 与 --timeout 提供 CI 硬预算，触发时退出码为 124。
• -q 只输出答案，--no-stream 缓冲后输出。
• stdin 最大 10 MiB。

非交互 Agent 会被提示自行做合理假设并使用非交互命令参数，因此更需要限定文件工具、shell allowlist、工作目录、预算和超时。

--allow-fs-tools 与 -S 是两层开关：前者决定 execute 是否存在，后者决定 execute 内哪些命令可运行。显式文件工具列表必须包含 read_file；当前可选项含 ls、read_file、write_file、edit_file、delete、glob、grep、execute。它不限制 async subagent 或非文件工具。

配置来源与优先级

通用选项

从高到低：

1. DEEPAGENTS_CODE_ 前缀环境变量。
2. 对应普通环境变量。
3. ~/.deepagents/config.toml。
4. 内置默认值。

用以下命令查“有效值 + 来源”，而不是猜测：

• dcode config show
• dcode config get <key>
• dcode config list
• dcode config path

均可加 --json。凭证只显示 configured / not configured，不打印值，适合提供诊断快照。

Dotenv

启动时从当前目录向上找到最近的项目 .env，再加载 ~/.deepagents/.env；shell export 始终优先。项目 .env 不能批准项目 MCP server，也不能设置 Auto classifier 的信任级配置，防止仓库自授权。

在不可信仓库中运行本地 dcode 仍有风险：.env、构建脚本和项目 hook 都可能影响执行。此类仓库应使用 remote sandbox，并拒绝项目级 MCP/hooks。

模型选择

启动模型优先级：

1. --model
2. [models].default
3. [models].recent
4. 只在 OpenAI、Anthropic、Google API、Google Cloud Project 四类凭证中做环境自动探测

/model 更新 recent，不覆盖 default。其他供应商仍可用显式模型或 saved default，只是不参加启动自动探测。

CLI --model-params 覆盖 config 的 constructor params；按模型的 TOML 子表浅合并供应商默认值。runtime profile（如 max_input_tokens、tool_calling）是另一层，用 --profile-override 或 config 的 profile 设置；错误 profile 会影响上下文显示、自动摘要阈值与能力判断。

重试与运行预算

模型重试优先级为 CLI --max-retries → CLI model params → provider params → provider retry table → global retry → SDK default。任意供应商需用它真正接受的构造参数名。

Graph step budget 默认 2000，合法范围 25–100000；CLI recursion limit → 环境变量 → TOML → 默认。它与 goal/rubric 的迭代限制不是同一预算。

供应商与端点

OpenAI、Anthropic、Gemini 默认安装；其他供应商按 extra 安装。dcode 支持 LangChain BaseChatModel 且必须支持 tool calling。当前官方表包含 Azure、Bedrock、Vertex、Ollama、Groq、Cohere、Fireworks、Together、Mistral、DeepSeek、OpenRouter、LiteLLM 等。

openai_codex 是独立供应商：通过浏览器登录 ChatGPT 订阅，不使用 OPENAI_API_KEY，也不等同 openai provider。

兼容 OpenAI / Anthropic wire protocol 的网关可用 base_url；但大多数 OpenAI-compatible 服务不实现 Responses API，需要显式关闭 Responses 模式或使用原生集成。供应商已有专用 LangChain 包时优先用专用包。

任意供应商可通过 class_path = "module:Class" 接入，但这会在启动时 import 并执行本机 Python 代码，信任级别与构建脚本相同。包必须安装进 dcode 自身的隔离环境。

Endpoint 与 key 必须成对解析

Endpoint 优先级：

1. config 的静态 base_url
2. DEEPAGENTS_CODE_ 前缀 endpoint 环境变量
3. 普通 endpoint 环境变量
4. /auth 与 key 一起保存的 endpoint
5. SDK 默认 endpoint

替换 gateway key 时也要替换/清空 gateway endpoint。/auth 将 key 与 base URL 作为一对保存；留空表示供应商默认，并会清掉不匹配的旧 endpoint。

凭证管理

推荐交互式 /auth，headless/CI 使用 dcode auth 或环境变量。Key 解析顺序：

1. DEEPAGENTS_CODE_<PROVIDER>_API_KEY
2. /auth / dcode auth set 保存的 key
3. 普通供应商环境变量

dcode auth set 默认从 stdin 读，避免 key 进入 argv 与 shell history，也可用 --from-env。它拒绝在交互终端里空等输入。

Tavily 的 web_search 需要单独 key；可在 /auth 保存或配置 TAVILY_API_KEY。LangSmith key 也可由 /auth 管理。

LangSmith tracing

Agent 自身 trace 与 Agent 运行 shell 命令产生的应用 trace 可以分项目：

• DEEPAGENTS_CODE_LANGSMITH_PROJECT：dcode 的模型、工具和编排。
• 普通 LANGSMITH_PROJECT：shell 内应用自身的 trace。

可用 replica project 双写。默认 trace 输入输出没有客户端 secret redaction；启用 redaction 后若无法配置，当前 run 会禁用 tracing。该功能不自动处理一般 PII、metadata 或 shell 子进程 trace。

数据目录与覆盖规则

~/.deepagents/ 保存 sessions、credentials、Agent memory/skills；~/.agents/ 保存跨工具共享 skills。

Skills 同名时从低到高是用户 dcode → 用户通用 → 项目 dcode → 项目通用，最高者整体覆盖；subagent 是项目覆盖用户。Instruction sources 不覆盖而是顺序拼接：包基础提示 → 用户 AGENTS.md → .deepagents/AGENTS.md → 根 AGENTS.md。

删除 sessions database 会不可逆丢失所有会话与 checkpoint。管理命令的 reset/delete 支持 --dry-run，应先预览。

排障顺序

1. dcode doctor 看安装、依赖、更新、tracing、MCP 和数据目录健康。
2. dcode config show 看每个值来自哪里。
3. dcode config path 确认实际读取的 config、dotenv、hooks 与 trust store。
4. /tools 或 dcode tools list 确认真实工具面。
5. 仅在需要时开启 DEEPAGENTS_CODE_DEBUG=1，并保护日志中的项目内容。