---
type: study
status: verified
created: 2026-08-11
updated: 2026-08-11
sensitivity: standard
tags:
  - langchain
  - deep-agents-code
  - dcode
  - cli
  - configuration
sources:
  - "https://docs.langchain.com/oss/deepagents/code"
  - "https://docs.langchain.com/oss/deepagents/code/overview"
  - "https://docs.langchain.com/oss/deepagents/code/quickstart"
  - "https://docs.langchain.com/oss/deepagents/code/configuration"
  - "https://docs.langchain.com/oss/deepagents/code/config-file"
  - "https://docs.langchain.com/oss/deepagents/code/providers"
  - "https://docs.langchain.com/oss/deepagents/code/credentials"
  - "https://docs.langchain.com/oss/deepagents/code/cli-reference"
last_verified: 2026-08-11
---

# 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 并在敏感动作前审批。常用命令按职责分组：

| 目的 | 命令 |
| --- | --- |
| 模型与推理 | `/model`、`/effort` |
| Agent 与会话 | `/agents`、`/threads`、`/clear`、`/force-clear` |
| 目标与质量 | `/goal`、`/rubric` |
| 上下文 | `/remember`、`/offload`/`/compact`、`/tokens` |
| 扩展 | `/skill:<name>`、`/plugins`、`/mcp`、`/reload` |
| 运维 | `/auth`、`/trace`、`/update`、`/version`、`/restart` |

`/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。

| 数据 | 位置 |
| --- | --- |
| 会话 checkpoint | `~/.deepagents/.state/sessions.db` |
| 输入历史 | `~/.deepagents/.state/history.jsonl` |
| 用户 Agent 指令 | `~/.deepagents/{agent}/AGENTS.md` |
| 项目指令 | `.deepagents/AGENTS.md` 与项目根 `AGENTS.md` |
| 用户 skills | `~/.deepagents/{agent}/skills/` |
| 通用用户 skills | `~/.agents/skills/` |
| 项目 skills | `.deepagents/skills/`、`.agents/skills/` |
| 用户/项目 subagents | 对应 `agents/` 目录 |

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`，并保护日志中的项目内容。