> ## Documentation Index
> Fetch the complete documentation index at: https://nvd-54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 深度智能体 CLI

> 基于深度智能体 SDK 构建的终端编程智能体

深度智能体 CLI 是一个基于 [深度智能体 SDK](/oss/javascript/deepagents/quickstart) 构建的开源编程智能体。
CLI 可与任何支持工具调用的大语言模型（LLM）配合使用，并允许你在输入之间切换 LLM。
它保留对话中学习内容的持久记忆，维护跨会话的上下文，使用可自定义的技能，并通过审批控制执行代码。

## 快速开始

<Steps>
  <Step title="安装和启动" icon="terminal">
    OpenAI、Anthropic 和 Google 默认已安装。其他提供商（Ollama、Groq、xAI 等）作为可选附加项提供——详见[提供商](/oss/javascript/deepagents/cli/providers)。

    <CodeGroup>
      ```bash Script theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      curl -LsSf https://langch.in/gh-da-cli | bash
      ```

      ```bash Optional extras theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      # 示例：安装并附带 Fireworks 和 Nvidia 提供商
      DEEPAGENTS_EXTRAS="fireworks,nvidia" curl -LsSf https://langch.in/gh-da-cli | bash

      # OpenAI、Anthropic 和 Gemini 默认包含
      # 查看所有附加项：
      # https://docs.langchain.com/oss/python/deepagents/cli/providers
      ```

      ```bash uv theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
      # 示例：安装并附带 Fireworks 和 Nvidia 提供商
      uv tool install 'deepagents-cli[fireworks,nvidia]'

      # OpenAI、Anthropic 和 Gemini 默认包含
      # 查看所有附加项：
      # https://docs.langchain.com/oss/python/deepagents/cli/providers
      ```
    </CodeGroup>

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents
    ```

    <img src="https://mintcdn.com/nvd-54/u9mURd9IHXggg6bM/oss/images/deepagents/deepagents-cli.png?fit=max&auto=format&n=u9mURd9IHXggg6bM&q=85&s=0e503149940e459f540c731ac9f164ca" alt="深度智能体 CLI" width="1572" height="1408" data-path="oss/images/deepagents/deepagents-cli.png" />
  </Step>

  <Step title="添加提供商凭据" icon="key">
    CLI 可与任何支持工具调用的 LLM 配合使用。使用 `/auth` 命令为所选提供商设置 API 密钥——有关完整流程和存储详情，请参阅[提供商凭据](/oss/javascript/deepagents/cli/configuration#provider-credentials)。

    有关其他提供商和无头运行，请参阅[提供商](/oss/javascript/deepagents/cli/providers)。

    <Note>
      网络搜索使用 [Tavily](https://tavily.com)，**不**通过 `/auth` 配置。如果启动时看到"Web search disabled — `TAVILY_API_KEY` is not set"，请将 `TAVILY_API_KEY=tvly-...` 添加到 `~/.deepagents/.env` 并运行 `/reload`（或重启）。参见[使用 Tavily 启用网络搜索](/oss/javascript/deepagents/cli/configuration#enable-web-search-with-tavily)。
    </Note>
  </Step>

  <Step title="给智能体一个任务" icon="message">
    ```txt theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    Create a Python script that prints "Hello, World!"
    ```

    智能体解释查询并在修改文件前提出带差异的更改供你批准。如果需要，它可以运行 shell 命令来测试代码、检查文档或搜索网络获取最新信息。
  </Step>

  <Step title="启用追踪（可选）" icon="chart-dots">
    要在 LangSmith 中记录智能体操作、工具调用和决策，请将以下内容添加到 `~/.deepagents/.env` 或在 shell 中导出变量：

    ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    LANGSMITH_TRACING=true
    LANGSMITH_API_KEY=lsv2_...
    LANGSMITH_PROJECT=optional-project-name  # 指定项目名称，否则默认为 "deepagents-cli"
    ```

    有关更多详细信息和用法，请参阅[使用 LangSmith 追踪](#trace-with-langsmith)。
  </Step>
</Steps>

<Note>
  深度智能体 CLI 不正式支持 Windows。Windows 用户可以尝试在 [Windows Subsystem for Linux (WSL)](https://learn.microsoft.com/en-us/windows/wsl/install) 下运行。
</Note>

## 功能

深度智能体 CLI 具有以下内置功能：

* <Icon icon="file" size={16} /> **文件操作** - 读取、写入和编辑文件的工具，使智能体能够管理和修改代码及文档。
* <Icon icon="terminal" size={16} /> **Shell 执行** - 执行命令以运行测试、构建项目、管理依赖项并与版本控制交互。
* <Icon icon="cloud" size={16} /> **[远程沙箱](/oss/javascript/deepagents/cli/remote-sandboxes)** - 在 LangSmith、Daytona、Modal、Runloop 或 AgentCore 中运行智能体工具，而非在本地机器上。链接页面涵盖提供商安装、凭据、沙箱标志（`--sandbox`、`--sandbox-id`、`--sandbox-setup`）和设置脚本。
* <Icon icon="search" size={16} /> **网络搜索** - 搜索网络获取最新信息和文档。需要在 [`TAVILY_API_KEY`](/oss/javascript/deepagents/cli/configuration#enable-web-search-with-tavily) 中设置 Tavily API 密钥。
* <Icon icon="globe" size={16} /> **HTTP 请求** - 向 API 和外部服务发出 HTTP 请求以进行数据获取和集成任务。
* <Icon icon="list-check" size={16} /> **任务规划和跟踪** - 将复杂任务分解为离散步骤并跟踪进度。
* <Icon icon="users" size={16} /> **[子智能体](/oss/javascript/deepagents/cli/subagents)** - 使用 `task` 工具委派工作。在 CLI 中，将自定义子智能体定义为 `AGENTS.md` 文件；链接页面涵盖路径、frontmatter 和示例。
* <Icon icon="brain" size={16} /> **[记忆存储和检索](/oss/javascript/deepagents/cli/memory-and-skills#memory)** - 跨会话存储和检索信息，使智能体能够记住项目约定和学习到的模式。
* <Icon icon="arrows-minimize" size={16} /> **上下文压缩和卸载** - 总结较旧的对话消息并将原始内容卸载到存储，在长会话期间释放上下文窗口空间。
* <Icon icon="user" size={16} /> **人机协作** - 对敏感的工具操作要求人工审批。
* <Icon icon="puzzle" size={16} /> **[技能](/oss/javascript/deepagents/cli/memory-and-skills#skills)** - 使用自定义专业知识和说明扩展智能体能力。
* <Icon icon="plug" size={16} /> **[MCP 工具](/oss/javascript/deepagents/cli/mcp-tools)** - 从[模型上下文协议](https://modelcontextprotocol.io/)服务器加载外部工具。
* <Icon icon="chart-dots" size={16} /> **[追踪](/oss/javascript/deepagents/cli/overview#trace-with-langsmith)** - 在 LangSmith 中追踪智能体操作以进行可观测性和调试。

<Accordion title="完整内置工具列表">
  ## 内置工具

  智能体附带以下内置工具，无需配置即可使用：

  | 工具                     | 描述                                                                                                                           | 人机协作           |
  | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------- |
  | `ls`                   | 列出文件和目录                                                                                                                      | -              |
  | `read_file`            | 读取文件内容；对部分模型支持多模态内容                                                                                                          | -              |
  | `write_file`           | 创建或覆盖文件                                                                                                                      | 必需<sup>1</sup> |
  | `edit_file`            | 对现有文件进行定向编辑                                                                                                                  | 必需<sup>1</sup> |
  | `glob`                 | 查找匹配模式的文件                                                                                                                    | -              |
  | `grep`                 | 跨文件搜索文本模式                                                                                                                    | -              |
  | `execute`              | 在本地或远程沙箱中执行 shell 命令                                                                                                         | 必需<sup>1</sup> |
  | `web_search`           | 使用 Tavily 搜索网络（需要 `TAVILY_API_KEY` — 参见[启用网络搜索](/oss/javascript/deepagents/cli/configuration#enable-web-search-with-tavily)） | 必需<sup>1</sup> |
  | `fetch_url`            | 获取网页并转换为 markdown                                                                                                            | 必需<sup>1</sup> |
  | `task`                 | 将工作委派给子智能体以并行执行                                                                                                              | 必需<sup>1</sup> |
  | `ask_user`             | 向用户提出自由形式或多选问题                                                                                                               | -              |
  | `compact_conversation` | 总结较旧的消息，将原始内容卸载到后端存储，并在上下文中替换为摘要                                                                                             | 混合<sup>2</sup> |
  | `write_todos`          | 为复杂工作创建和管理任务列表                                                                                                               | -              |

  <sup>1</sup>：可能具有破坏性的操作在执行前需要用户批准。要跳过人工审批，你可以切换自动批准（shift+tab）或使用该选项启动：

  ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  deepagents -y
  # 或
  deepagents --auto-approve
  ```

  <Note>
    在非交互模式下运行 CLI（通过 `-n` 或管道输入的 stdin）时，即使使用 `-y`/`--auto-approve`，shell 执行默认也是禁用的。使用 `-S`/`--shell-allow-list` 来允许特定命令（例如 `-S "pytest,git,make"`），`recommended` 表示安全默认值，或 `all` 允许任何命令。也支持 `DEEPAGENTS_CLI_SHELL_ALLOW_LIST` 环境变量。更多详情请参阅[非交互模式和管道](#non-interactive-mode-and-piping)。
  </Note>

  <sup>2</sup>：当 Token 使用量超过模型感知阈值时，CLI 会自动在后台卸载对话。卸载通过 LLM 总结较旧的消息，并将原始内容输出到存储（`/conversation_history/{thread_id}.md`），在上下文中替换为摘要。如果需要，智能体仍然可以从卸载的文件中检索完整历史记录。`compact_conversation` 工具让智能体（或你）可以按需触发卸载。作为工具调用时，默认需要用户批准。
</Accordion>

<Tip>
  [观看演示视频](https://youtu.be/IrnacLa9PJc?si=3yUnPbxnm2yaqVQb)了解深度智能体 CLI 的工作方式。
</Tip>

## 命令参考

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 使用特定的智能体配置
deepagents --agent mybot

# 使用特定模型（provider:model 格式或自动检测）
deepagents --model anthropic:claude-opus-4-7
deepagents --model gpt-5.5

# 自动批准工具使用（跳过人机协作提示）
deepagents -y

# 列出目录内容，然后将目录摘要作为第一个提示——命令先运行，然后提交提示
# 提示无法访问命令输出
deepagents --startup-cmd "ls -la" -m "Summarize what's in this directory"

# 非交互模式带启动命令：在任务运行前显示 git 状态
# 任务无法访问命令输出
deepagents --startup-cmd "git diff --stat" -n "Review these changes"
```

<AccordionGroup>
  <Accordion title="命令行选项" icon="flag">
    | 选项                              | 描述                                                                                                                                                                            |
    | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `-a`, `--agent NAME`            | 使用带有独立记忆的命名智能体。覆盖 `config.toml` 中的 `[agents].recent`。默认：`agent`（或如果设置了 `[agents].recent` 则为最近使用的智能体）                                                                          |
    | `-M`, `--model MODEL`           | 使用特定模型（`provider:model`）                                                                                                                                                      |
    | `--model-params JSON`           | 以 JSON 字符串传递给模型的额外关键字参数（例如 `'{"temperature": 0.7}'`）                                                                                                                          |
    | `--default-model [MODEL]`       | 设置默认模型                                                                                                                                                                        |
    | `--clear-default-model`         | 清除默认模型                                                                                                                                                                        |
    | `-r`, `--resume [ID]`           | 恢复会话：`-r` 恢复最近的，`-r <ID>` 恢复特定线程                                                                                                                                              |
    | `-m`, `--message TEXT`          | 会话启动时自动提交的初始提示（交互模式）                                                                                                                                                          |
    | `--skill NAME`                  | 启动时调用技能                                                                                                                                                                       |
    | `--startup-cmd CMD`             | 启动时运行的 shell 命令，在第一个提示之前。输出在记录中渲染供你参考，但**不会**添加到智能体的消息历史中。要将命令输出交给智能体，请通过 stdin 管道传入（例如 `git diff \| deepagents -n "Review these changes"`）。非零退出和超时会发出警告但不会中止；非交互模式应用 60 秒超时。 |
    | `-n`, `--non-interactive TEXT`  | 非交互运行单个任务并退出。除非设置了 `--shell-allow-list`，否则 shell 被禁用                                                                                                                          |
    | `--max-turns N`                 | 在非交互模式中限制智能体轮次。超过时以代码 124 退出。需要 `-n` 或管道 stdin。参见[使用 `--max-turns` 限制轮次](#non-interactive-mode-and-piping)                                                                    |
    | `-q`, `--quiet`                 | 适合管道的干净输出——仅智能体的响应发送到 stdout。需要 `-n` 或管道 stdin                                                                                                                                |
    | `--no-stream`                   | 缓冲完整响应并一次性写入 stdout，而不是流式输出。需要 `-n` 或管道 stdin                                                                                                                                 |
    | `--stdin`                       | 明确从 stdin 读取输入而不是自动检测。当 stdin 不可用或是 TTY 时会清楚地报错                                                                                                                               |
    | `-y`, `--auto-approve`          | 自动批准所有工具调用而不提示（禁用人机协作）。在交互式会话中使用 `Shift+Tab` 切换                                                                                                                               |
    | `-S`, `--shell-allow-list LIST` | 逗号分隔的自动批准 shell 命令列表，`'recommended'` 表示安全默认值，或 `'all'` 允许任何命令。适用于 `-n` 和交互模式                                                                                                  |
    | `--json`                        | 从管理子命令（`agents`、`threads`、`skills`、`update`）发出机器可读的 JSON。输出信封：`{"schema_version": 1, "command": "...", "data": ...}`                                                          |
    | `--sandbox TYPE`                | 用于代码执行的远程沙箱：`none`（默认）、`langsmith`、`agentcore`、`modal`、`daytona`、`runloop`。LangSmith 已包含；AgentCore/Modal/Daytona/Runloop 需要附加项                                                |
    | `--sandbox-id ID`               | 复用现有沙箱（跳过创建和清理）                                                                                                                                                               |
    | `--sandbox-setup PATH`          | 创建沙箱后运行的设置脚本路径                                                                                                                                                                |
    | `--mcp-config PATH`             | 添加一个显式 MCP 配置作为最高优先级来源（与自动发现的配置合并）                                                                                                                                            |
    | `--no-mcp`                      | 禁用所有 MCP 工具加载                                                                                                                                                                 |
    | `--trust-project-mcp`           | 信任项目级带 stdio 服务器的 MCP 配置（跳过批准提示）                                                                                                                                              |
    | `--profile-override JSON`       | 以 JSON 字符串覆盖模型配置文件字段（例如 `'{"max_input_tokens": 4096}'`）。合并到配置文件配置文件覆盖之上                                                                                                       |
    | `--acp`                         | 作为 ACP 服务器通过 stdio 运行，而不是启动交互式 UI                                                                                                                                             |
    | `-v`, `--version`               | 显示版本                                                                                                                                                                          |
    | `-h`, `--help`                  | 显示帮助                                                                                                                                                                          |
  </Accordion>

  <Accordion title="CLI 命令" icon="terminal">
    | 命令                                                     | 描述                                                                                                                                                                     |
    | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `deepagents help`                                      | 显示帮助                                                                                                                                                                   |
    | `deepagents agents list`                               | 列出所有智能体（别名：`ls`）                                                                                                                                                       |
    | `deepagents agents reset --agent NAME`                 | 清除智能体记忆并重置为默认。支持 `--dry-run`                                                                                                                                           |
    | `deepagents agents reset --agent NAME --target SOURCE` | 从另一个智能体复制记忆                                                                                                                                                            |
    | `deepagents update`                                    | 检查并安装 CLI 更新                                                                                                                                                           |
    | `deepagents skills list [--project]`                   | 列出所有技能（别名：`ls`）                                                                                                                                                        |
    | `deepagents skills create NAME [--project]`            | 使用模板 `SKILL.md` 创建新技能。幂等——重新创建已有技能会打印信息消息而不是错误                                                                                                                         |
    | `deepagents skills info NAME [--project]`              | 显示技能的详细信息                                                                                                                                                              |
    | `deepagents skills delete NAME [--project] [-f]`       | 删除技能及其内容。支持 `--dry-run`                                                                                                                                                |
    | `deepagents threads list [--agent NAME] [--limit N]`   | 列出会话（别名：`ls`）。默认限制：20。`-n` 是 `--limit` 的短标志。附加标志：`--sort {created,updated}`、`--branch TEXT`（按 git 分支过滤）、`-v`/`--verbose`（显示所有列包括分支、创建时间和初始提示）、`-r`/`--relative`（相对时间戳） |
    | `deepagents threads delete ID`                         | 删除会话。支持 `--dry-run`                                                                                                                                                    |
    | `deepagents mcp login NAME [--config PATH]`            | 为标记为 `auth: "oauth"` 的 MCP 服务器运行 OAuth 登录流程。参见 [MCP 工具](/oss/javascript/deepagents/cli/mcp-tools#oauth-login)                                                          |
    | `deepagents deploy`                                    | 将智能体部署到 LangSmith。参见[使用 CLI 部署](/oss/javascript/deepagents/deploy)                                                                                                     |

    所有管理子命令支持 `--json` 用于机器可读输出。详情请参阅[命令行选项](#command-line-options)。

    破坏性命令（`agents reset`、`skills delete`、`threads delete`）支持 `--dry-run` 来预览将要发生的事情而不实际执行更改。在 JSON 模式下，`--dry-run` 返回相同的信封并带有 `dry_run: true` 字段。
  </Accordion>
</AccordionGroup>

## 配置

有关完整参考——包括 `config.toml` 模式、提供商参数、配置文件覆盖和钩子配置——请参阅[配置](/oss/javascript/deepagents/cli/configuration)。

CLI 将所有配置存储在 `~/.deepagents/` 下。在该目录中，每个智能体有自己的子目录（默认：`agent`）：

| 路径                            | 用途                                                                                      |
| ----------------------------- | --------------------------------------------------------------------------------------- |
| `~/.deepagents/config.toml`   | 模型和智能体默认值、提供商设置、构造参数、配置文件覆盖、主题、更新设置、MCP 信任存储                                            |
| `~/.deepagents/.env`          | 全局 API 密钥和秘密。参见[配置](/oss/javascript/deepagents/cli/configuration#environment-variables) |
| `~/.deepagents/hooks.json`    | 生命周期事件钩子（会话开始/结束、任务完成等）                                                                 |
| `~/.deepagents/<agent_name>/` | 每个智能体的记忆、技能和对话线程                                                                        |
| `.deepagents/`（项目根目录）         | 项目特定的记忆和技能，在 git 仓库中运行时加载                                                               |

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
# 列出所有配置的智能体
deepagents agents list
```

## 交互模式

像在聊天界面中一样自然地输入。
智能体将使用其内置工具、技能和记忆来帮助你完成任务。

<AccordionGroup>
  <Accordion title="斜杠命令" icon="slash">
    在 CLI 会话中使用这些命令：

    * `/model` - 切换模型或打开交互式模型选择器。
    * `/agents` - 在预配置的智能体之间热切换而不重新启动。参见[命令参考](/oss/javascript/deepagents/cli/overview#command-reference)了解详情
    * `/auth` - 管理模型提供商的存储 API 密钥。参见[提供商凭据](/oss/javascript/deepagents/cli/configuration#provider-credentials)了解详情
    * `/remember [context]` - 回顾对话并更新记忆和技能。可选择传递额外上下文
    * `/skill:<name> [args]` - 按名称直接调用技能。技能的 `SKILL.md` 说明连同你提供的任何参数一起注入到提示中
    * `/skill-creator [args]` - 创建有效智能体技能的指南
    * `/offload`（别名 `/compact`）- 通过将消息卸载到存储并用摘要占位符替换来释放上下文窗口空间。如果需要，智能体可以从卸载的文件中检索完整历史记录
    * `/tokens` - 显示当前上下文窗口 Token 使用量明细
    * `/clear` - 清除对话历史并开始新线程
    * `/threads` - 浏览和恢复之前的对话线程
    * `/mcp` - 显示活跃的 MCP 服务器和工具
    * `/reload` - 重新读取 `.env` 文件、刷新配置并重新发现技能而无需重启。对话状态保留。参见 [`DEEPAGENTS_CLI_` 前缀](/oss/javascript/deepagents/cli/configuration#deepagents_cli_-prefix)了解覆盖行为
    * `/theme` - 打开交互式主题选择器以切换颜色主题。提供内置主题以及任何[用户定义的主题](/oss/javascript/deepagents/cli/configuration#themes)
    * `/update` - 内联检查并安装 CLI 更新。检测你的安装方法（uv、Homebrew、pip）并运行适当的升级命令
    * `/auto-update` - 切换自动更新的开关
    * `/trace` - 在 LangSmith 中打开当前线程（需要 `LANGSMITH_API_KEY`）
    * `/editor` - 在外部编辑器中打开当前提示（`$VISUAL` / `$EDITOR`）。参见[外部编辑器](/oss/javascript/deepagents/cli/configuration#external-editor)
    * `/changelog` - 在浏览器中打开 CLI 更新日志
    * `/docs` - 在浏览器中打开文档
    * `/feedback` - 打开 GitHub issues 页面以提交 bug 报告或功能请求
    * `/version` - 显示已安装的 `deepagents-cli` 和 SDK 版本
    * `/help` - 显示帮助和可用命令
    * `/quit` - 退出 CLI
  </Accordion>

  <Accordion title="Shell 命令" icon="prompt">
    输入 `!` 进入 shell 模式，然后输入你的命令。

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    git status
    npm test
    ls -la
    ```
  </Accordion>

  <Accordion title="键盘快捷键" icon="keyboard">
    **通用**

    | 快捷键                                               | 操作           |
    | ------------------------------------------------- | ------------ |
    | `Enter`                                           | 提交提示         |
    | `Shift+Enter`、`Ctrl+J`、`Alt+Enter` 或 `Ctrl+Enter` | 插入换行         |
    | `Ctrl+A`                                          | 选择输入中的所有文本   |
    | `@filename`                                       | 自动补全文件并注入内容  |
    | `Shift+Tab` 或 `Ctrl+T`                            | 切换自动批准       |
    | `Ctrl+U`                                          | 删除到行首        |
    | `Ctrl+X`                                          | 在外部编辑器中打开提示  |
    | `Ctrl+O`                                          | 展开/折叠最近的工具输出 |
    | `Escape`                                          | 中断当前操作       |
    | `Ctrl+C`                                          | 中断或退出        |
    | `Ctrl+D`                                          | 退出           |
  </Accordion>
</AccordionGroup>

## 非交互模式和管道

使用 `-n` 运行单个任务而不启动交互式 UI：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
deepagents -n "Write a Python script that prints hello world"
```

你也可以通过 stdin 管道输入。当输入被管道传入时，CLI 自动以非交互模式运行：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
echo "Explain this code" | deepagents
cat error.log | deepagents -n "What's causing this error?"
git diff | deepagents -n "Review these changes"
git diff | deepagents --skill code-review -n 'summarize changes'
```

当你将管道输入与 `-n` 或 `-m` 结合使用时，管道内容先出现，然后是你传递给标志的文本。

<Note>
  最大管道输入大小为 10 MiB。
</Note>

在非交互模式下，shell 执行默认禁用。使用 `-S`/`--shell-allow-list` 启用特定命令（例如 `-S "pytest,git,make"`），`recommended` 表示安全默认值，或 `all` 允许任何命令。

<AccordionGroup>
  <Accordion title="使用 `--max-turns` 限制轮次" icon="gauge">
    CI/CD 管道中长期运行或行为异常的智能体可能无限循环。`--max-turns N` 为操作者提供了一个硬上限而无需接触 SDK 内部：

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents -n "fix the failing tests" --max-turns 10
    ```

    `N` 必须是正整数，并覆盖内部安全默认值（否则会限制失控循环）。超出预算时以代码 124 退出（匹配 GNU `timeout`），以便 CI 可以区分预算命中和通用故障。需要 `-n` 或管道 stdin；否则以代码 2 退出。
  </Accordion>

  <Accordion title="干净输出和缓冲" icon="buffer">
    使用 `-q` 获得适合管道到其他命令的干净输出，使用 `--no-stream` 在写入 stdout 之前缓冲完整响应（而不是流式输出）：

    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    deepagents -n "Generate a .gitignore for Python" -q > .gitignore
    deepagents -n "List dependencies" -q --no-stream | sort
    ```

    在非交互模式下，智能体被指示做出合理假设并自主进行，而不是提出澄清性问题。它还倾向于使用非交互命令变体（例如 `npm init -y`、`apt-get install -y`）。
  </Accordion>

  <Accordion title="Shell 执行示例" icon="shield-check">
    ```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
    # 允许特定命令（针对列表验证）
    deepagents -n "Run the tests and fix failures" -S "pytest,git,make"

    # 使用精选的安全命令列表
    deepagents -n "Build the project" -S recommended

    # 允许任何 shell 命令
    deepagents -n "Fix the build" -S all
    ```
  </Accordion>
</AccordionGroup>

<Warning>
  **请谨慎使用。**

  `-S all`（或 `--shell-allow-list all`）允许智能体执行任意 shell 命令而无需人工确认。
</Warning>

## 使用 LangSmith 追踪

启用 [LangSmith](https://smith.langchain.com?utm_source=docs\&utm_medium=cta\&utm_campaign=langsmith-signup\&utm_content=oss-deepagents-cli-overview) 追踪以在 LangSmith 项目中查看智能体操作、工具调用和决策。

将追踪密钥添加到 `~/.deepagents/.env` 中，以便在每个会话中启用追踪而无需每个 shell 导出：

```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_...
LANGSMITH_PROJECT=optional-project-name  # 指定项目名称，否则默认为 "deepagents-cli"
```

要为特定项目覆盖，在项目目录中添加相同的密钥到 `.env`。有关完整加载顺序，请参阅[环境变量](/oss/javascript/deepagents/cli/configuration#environment-variables)。

如果你更喜欢，也可以将这些设置为 shell 环境变量。shell 导出始终优先于 `.env` 值，因此这是临时覆盖或测试的好选择：

```bash theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
export LANGSMITH_TRACING=false
```

<Accordion title="将智能体追踪与应用追踪分离">
  当从 LangChain 应用程序以编程方式调用 CLI（例如作为[非交互模式](#non-interactive-mode-and-piping)的子进程）时，你的应用和 CLI 都会产生 LangSmith 追踪。默认情况下，它们都落在同一个项目中。

  要将 CLI 追踪发送到专用项目，设置 `DEEPAGENTS_CLI_LANGSMITH_PROJECT`：

  ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  DEEPAGENTS_CLI_LANGSMITH_PROJECT=my-deep-agent-execution
  ```

  然后为父应用程序的追踪配置 `LANGSMITH_PROJECT`：

  ```bash title="~/.deepagents/.env" theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  LANGSMITH_PROJECT=my-app-traces
  ```

  这样可以保持应用级别的可观测性清洁，同时在单独的项目中捕获智能体的内部执行。

  你还可以使用 [`DEEPAGENTS_CLI_` 前缀](/oss/javascript/deepagents/cli/configuration#deepagents_cli_-prefix)（例如 `DEEPAGENTS_CLI_LANGSMITH_API_KEY`）将 LangSmith 凭据限定到 CLI。
</Accordion>

配置后，CLI 显示带有 LangSmith 项目链接的状态行。在支持的终端中，点击链接直接打开。你也可以使用 `/trace` 打印 URL 并在浏览器中打开。

```sh theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
✓ LangSmith tracing: 'my-project'
```

***

<div className="source-links">
  <Callout icon="terminal-2">
    [将这些文档连接](/use-these-docs)到 Claude、VSCode 等，通过 MCP 获取实时答案。
  </Callout>

  <Callout icon="edit">
    [在 GitHub 上编辑此页面](https://github.com/langchain-ai/docs/edit/main/src/oss/deepagents/cli/overview.mdx)或[提交 issue](https://github.com/langchain-ai/docs/issues/new/choose)。
  </Callout>
</div>
