> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enconvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 代码运行器

> 让智能体在 Mac 上的真实终端中运行 shell 命令、脚本、构建和开发服务器。

代码运行器（Code Runner）为智能体提供一个 Mac 上的真实终端。你可以用它进行构建、测试，运行脚本、包管理工具和开发服务器。能运行什么，取决于你安装的程序和你的账户权限。

> [!WARNING]
>
> 命令会真实执行，并拥有你的账户对文件和网络的访问权限，除非你开启了智能体的 **沙盒**。任何会安装软件、修改文件或影响在线服务的命令，请在运行前先审查。

## 开始之前

* 为你正在使用的智能体打开代码运行器。
* 聊天中的 **权限** 标签决定智能体何时先征求你的同意。**请求批准** 会在运行命令前询问，**替我批准** 只在操作看起来不安全时询问。参阅[批准操作](https://docs.enconvo.ai/zh/ai/agents.md)。
* 要将智能体的命令限制在工作文件夹内，避免接触你的密钥和其他应用，请在同一标签中开启 **沙盒**。参见[智能体沙盒](https://docs.enconvo.ai/zh/configuration/sandbox.md)。

## 运行命令

给智能体一个文件夹和一个具体的任务：

> 在我的示例项目里运行现有的测试命令并报告结果。不要修改文件。

智能体会显示命令的输出，并告诉你它已经结束还是仍在运行。要阅读、编辑和搜索文件，智能体会改用[文件工具](https://docs.enconvo.ai/zh/ai/file-tools.md)。

## 命令如何运行

每个命令都在伪终端中运行，因此需要输入的命令可以直接得到回应，无需启动新进程。

| 模式 | 适用场景 |
| - | - |
| **oneshot** | 会自行结束的命令，例如测试、构建或脚本 |
| **long\_running** | 服务器、监视进程，以及等待外部事件的进程 |
| **interactive** | REPL、终端应用和交互式命令行会话 |

如果结果中有 `status: running` 和一个 `session_id`，说明进程仍在运行。智能体可以 **read** 它的输出、向它 **write** 输入，或 **stop** 它。要回应提示，智能体需要向该会话写入；启动另一个命令并不能回应它。

## 等待任务完成

当任务需要等待时（例如等待构建写入输出或服务器启动），智能体会使用 **Wait For** 工具，而不是在 shell 中循环等待。它会在不运行命令的情况下等待以下任一条件：

* 出现指定文件
* 日志文件中出现某一行
* 某个进程或命令会话结束
* 某个端口开放，或某个地址响应

等待状态会显示在聊天的后台任务中。当条件满足、失败或超时时，智能体会收到通知，在此期间它可以继续处理其他工作。

## 工作文件夹与时间限制

如果智能体设置了 `workDir`，命令就在其中运行，否则在聊天的工作文件夹中运行。它们使用你的 shell，并已配置好你的项目和 Python 虚拟环境。除非在同一会话中运行，不同的命令不会共享临时的 shell 变量。

首次等待时间与命令的硬性时间限制是分开的。oneshot 命令最多等待 30 秒获取结果；如果到时仍在运行，智能体会拿到目前为止的输出，而任务会继续执行。命令默认在 30 分钟后被停止。对于服务器或监视进程，请使用 long\_running 模式，而不要把它当作失败了的 oneshot 命令。

## 设置

打开 **设置 → 插件 → Code Runner**。

| 设置 | 作用 |
| - | - |
| **Enable RTK** | 在智能体阅读之前压缩较长的命令输出，从而消耗更少的 token。默认打开 |

如果压缩后的输出中缺少你需要的细节，请要求运行更有针对性的命令，或查看日志中的相关部分。输出被截断并不能证明命令执行成功。

## 故障排除

| 问题 | 解决方法 |
| - | - |
| 找不到命令 | 确认该程序已安装，并且在你的 shell 中可用 |
| 命令在等待输入 | 让智能体在同一会话中回应提示。无人能提供输入的等待命令会立即结束 |
| 权限被拒绝 | 检查目标路径和 macOS 权限。如果开启了沙盒，点击步骤下方的那一行即可查看被拦截的内容 |
| 命令超时 | 阅读最后的输出，并在重新运行前选择合适的模式 |
| 服务器一直在运行 | 不再需要时，让智能体停止它的会话 |

## 相关内容

> [card] [文件与文件夹](https://docs.enconvo.ai/zh/ai/file-tools.md)
>
> 让智能体查找、阅读和编辑文件。

> [card] [智能体](https://docs.enconvo.ai/zh/ai/agents.md)
>
> 设置智能体的工具，以及它何时先征求同意。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.