AutoGPT Platform 中的 Claude Code Execution 块：在 E2B 沙箱内运行 Agentic 编码任务

本文围绕 AutoGPT Platform 的 Claude Code Execution 块（官方文档见 docs/integrations/block-integrations/claude_code.md）展开：它把 Anthropic 的 Claude Code 命令行编程助手部署到 E2B 云端 Linux 沙箱中，让 AI 在隔离环境里自主创建文件、安装依赖、执行命令并构建完整应用。读完本文，你将掌握该块的全部输入输出契约、三套会话延续机制、文件产物提取规则，并能依据源码组织出"文档转应用"与"多轮迭代开发"等可落地的 Agent 编排方案。

这是什么块：把 Claude Code 变成可编排的图节点

Claude Code Execution 位于 BlockCategory.DEVELOPER_TOOLS（"Developer tools such as GitHub blocks"）与 BlockCategory.AI 两个分类之下（见 claude_code.py 中构造函数对其 categories 的设置）。它的定位是委托式编码：上游 Agent 不需要逐行写代码，而是把一个自然语言任务丢给 Claude Code，由 Claude Code 在沙箱内自主完成多步骤开发工作。

块级能力（对应官方文档 "What it does"）包括：

• 创建/修改文件；
• 安装依赖（npm、pip 等）；
• 运行终端命令；
• 构建并测试应用；
• 一次执行覆盖"从空目录到可运行工程"的完整闭环。

在图上它是普通 Node，可以与 Firecrawl、GitHub、Webhook 等任何块自由连线，从而把"抓取文档 → 让 Claude 写代码 → 推送仓库"这类流水线变成可视化工作流，而非一次性脚本。

工作流程：沙箱内的六阶段生命周期

官方文档给出的执行阶段为：

1. 创建或连接 E2B 沙箱——一个安全、隔离的 Linux 运行环境；
2. 安装最新版 Claude Code；
3. 可选执行 Setup Commands 以准备环境；
4. 执行 Prompt——Claude Code 在此阶段创建/编辑文件、安装依赖、运行命令、构建测试应用；
5. 提取本轮产生/修改的全部文件（文本文件与图片、PDF 等二进制文件）；
6. 返回响应与文件，并按配置决定沙箱是否保留供后续任务复用。

源码级实现：如何一步步发生

将上述流程映射到 execute_claude_code()，细节如下：

• 沙箱创建：新会话走 BaseAsyncSandbox.create(template="base", api_key=..., timeout=timeout, envs={"ANTHROPIC_API_KEY": anthropic_api_key})。注意该块刻意选用通用 "base" 模板而非预置 Claude 的镜像，把 ANTHROPIC_API_KEY 作为沙箱环境变量注入——这正是它能始终拿到"最新版本"的原因。

• Claude Code 安装：随后在沙箱内执行 npm install -g @anthropic-ai/claude-code@latest（安装命令超时 120 秒，失败则抛错）。

• Setup Commands：逐条执行 setup_commands，任一条退出码非 0 即中止并抛出包含 stdout/stderr 的异常。

• 命令构造：核心调用被组织为

  cd <working_directory> && echo '<prompt>' | claude <flags>
  

  其中基础 flags 固定为 -p --dangerously-skip-permissions --output-format json：-p 表示非交互式 print 模式，--dangerously-skip-permissions 跳过交互式权限确认（沙箱本身已隔离风险），--output-format json 则保证结果可被程序解析。新会话追加 --session-id <id>，续接会话则改用 --resume <id>（详见下文"会话延续"）。

• 安全转义：working_directory 与 session_id 均经 shlex.quote() 处理；Prompt 则通过 _escape_prompt() 以单引号包裹并转义内部单引号（见 claude_code.py），防止 shell 注入。

• 超时策略：Claude Code 命令本身的 timeout=0（不设命令级超时），由沙箱级 timeout 兜底——避免复杂任务在命令层被过早掐断。

• 文件筛选时间戳：执行前先在沙箱内运行 date -u -d '1 second ago' +%Y-%m-%dT%H:%M:%S（故意取 1 秒前，规避文件创建与计时之间的竞态），仅提取该时间点之后被创建或修改的文件。

断点续跑：三种会话延续机制

官方文档强调该块通过三种机制支持多轮对话：

• 同一沙箱延续（session_id + sandbox_id）：前一轮 dispose_sandbox=false 保住沙箱，本轮填回两者即可在同一活沙箱上续接；
• 新沙箱上下文恢复（conversation_history）：若原沙箱已超时销毁，将历史灌入新沙箱；
• 沙箱销毁控制（dispose_sandbox）：为多轮对话保活沙箱。

对应源码逻辑清晰可读：

• 若提供 session_id 但缺少 sandbox_id，直接抛 ValueError，提示"会话状态存储在原始沙箱中，沙箱超时请改用 conversation_history 恢复"（见 claude_code.py）；
• 存在 existing_sandbox_id 时调用 BaseAsyncSandbox.connect() 重连，否则走 create；
• 重连场景下不再重装 Claude Code、不执行 setup_commands，延续原始环境；
• 提供 conversation_history 且无 session_id 时，把 Previous conversation context: ... 经转义后作为 --append-system-prompt 附加到系统提示词，实现新沙箱上的上下文"搬移"；
• 会话 ID：传入则沿用，否则 str(uuid.uuid4()) 生成。

输入参数完整参考

官方文档的输入表如下，本表补充了源码中的类型与默认值（源码见 claude_code.py）：

输入	类型/默认值	说明
E2B Credentials	必填（API Key 凭据）	创建沙箱所需 E2B 平台 API Key。可在 E2B 官网申请后接入平台凭据体系
Anthropic Credentials	必填（API Key 凭据）	驱动 Claude Code 的 Anthropic API Key，在 Anthropic Console 创建后接入平台
Prompt	str，默认 ""	交给 Claude Code 的任务描述；可要求其创建文件、装包、跑命令或完成复杂编码任务。占位示例："Create a hello world index.html file"
Timeout	int，默认 300（秒）	沙箱超时时间，复杂任务应调大。注意：仅新建沙箱时生效——通过 sandbox_id 重连沿用原始超时
Setup Commands	list[str]，默认 []	在 Claude Code 运行前执行的 shell 命令（如安装项目依赖）。标记为高级参数
Working Directory	str，默认 /home/user	Claude Code 的工作目录。标记为高级参数
Session ID	str，默认 ""	续接旧会话用，留空开启新会话。标记为高级参数
Sandbox ID	str，默认 ""	重连既有沙箱的 ID，续接会话时必须提供（须配合 session_id）。标记为高级参数
Conversation History	str，默认 ""	前次会话历史，用于原沙箱超时后在新沙箱恢复上下文。标记为高级参数
Dispose Sandbox	bool，默认 true	执行后是否立即销毁沙箱；设为 false 可让会话稍后继续（需同时保存输出的 sandbox_id 与 session_id）。标记为高级参数

需要说明：凭据字段在块中属于 CredentialsMetaInput 类型（provider 分别限定为 e2b 与 anthropic，见 providers.py），在平台上通过"连接凭据/管理密钥"预先绑定，而不是把明文 Key 直接写进图里。其余全部参数中仅 Prompt 为常规参数，其余能力（超时、目录、会话续接等）都收敛在高级面板，保证默认场景的简洁性。

输出字段完整参考

输出	类型	说明
Response	str	Claude Code 本轮执行的响应/结果文本
Files	list[SandboxFileOutput]	本轮创建/修改的文件列表（文本与图片、PDF 等二进制均含）。每个元素含 path、relative_path、name、content、workspace_ref 五字段；二进制文件内容为占位符，需经 workspace_ref 访问工作区中实体
Conversation History	str	含本轮在内的完整对话历史；传给 conversation_history 输入可在新沙箱恢复上下文
Session ID	str	本会话 ID，与 sandbox_id 一起回传即可延续会话
Sandbox ID	str | null	沙箱实例 ID（dispose_sandbox=true 时输出为 null）；配合 session_id 回传可延续会话
Error	str	执行失败时的错误信息

从 run() 的实现可确认：即使没有文件生成，files 也会产出空列表而非缺字段；sandbox_id 在 dispose_sandbox=true 时一律输出 None，避免给下游"沙箱仍存活"的错误信号；会话续接所需的两把"钥匙"（session_id、sandbox_id）以及用于新沙箱恢复的 conversation_history 都被无条件产出，方便直接接线回本块输入。

产物文件提取与 Workspace 持久化

文件提取复用了一套共享工具 extract_and_store_sandbox_files()（Code Executor 等沙箱块共用），核心逻辑位于 extract_sandbox_files 与 store_sandbox_files：

• 文件发现：沙箱内执行 find <working_directory> -type f -newermt <since_timestamp> -not -path '*/node_modules/*' -not -path '*/.git/*'，天然剔除依赖与版本库噪声；
• 扩展名白名单过滤：约 80 种文本扩展名（.py/.js/.ts/.html/.json/.md/.go/.rs/... 与 Dockerfile 等）和二进制扩展名（图片 .png/.jpg/.webp、文档 .pdf、压缩包、音视频、字体等）构成允许集，未识别扩展名的文件被跳过；
• 体积保护：单文件超过 MAX_BINARY_FILE_SIZE = 50MB 即跳过（防止意外抽取巨型文件导致 OOM），抽取前先用 stat 探测大小；
• 内容落库：文本文件解码 UTF-8 后放入 content 字段保持向后兼容；二进制文件经 MIME 猜测、base64 组装为 data URI 后调用 store_media_file 写入工作区，返回形如 workspace://{id}#mime 的引用；若工作区存储失败，则在不超过配置上限 max_file_size_mb 的前提下回退为内联 data URI，避免二进制数据丢失。

因此输出字段中的 workspace_ref 是把沙箱产物接续到 Agent 工作区的关键桥梁——例如接下去用 GitHub 类块推送仓库、或用展示类块渲染截图/PDF。关于 workspace:// URI 语义可进一步参考 workspace-media-architecture.md。

成本计量：按真实消耗计费而非固定费率

ClaudeCodeBlock 在平台计费配置中被注册为 COST_USD 类型、每 1 美元记 150 积分（见 block_cost_config.py）。配置注释明确：Claude Code CLI 在 JSON 响应中给出的 total_cost_usd 已经汇总了 Anthropic LLM 与内部工具调用（tool-call）的全部开销，而 E2B 沙箱基础设施成本（约 $0.00028/s）被直接吸收进这 1.5× 的计费边际内。

机制上，块执行成功后会调用 _record_cli_cost()：从 JSON 输出中取出 total_cost_usd，通过 merge_stats(NodeExecutionStats(provider_cost=..., provider_cost_type="cost_usd")) 上抛给钱包结算；若字段缺失则静默跳过，不产生费用。

配套测试 claude_code_cost_test.py 验证了计费解析与乘法逻辑，例如 $0.0134 × 150 = 2.01 → ceil 取整 = 3 积分，且"亚美分"级的小额运行也会按 ceil 兜底到至少 1 积分，杜绝零积分泄漏；同时测试了 stats 缺失/无成本场景下返回 0（预检路径）。

错误处理与沙箱回收

异常路径同样经过精细设计：所有内部失败被包装成 ClaudeCodeExecutionError，它携带 sandbox_id（见 claude_code.py），因为当 dispose_sandbox=false 时沙箱可能在出错后仍然存活、产生"孤儿资源"。run() 中捕获该异常后会：

1. 在 error 输出中给出可读错误信息；
2. 当配置为保留沙箱且存在可用的 sandbox_id 时，额外把该 ID 输出，供后续节点重连排查或显式清理。

成功路径的回收则落在 finally：若 dispose_sandbox=true 且沙箱对象存在，调用 sandbox.kill() 彻底销毁。

典型编排用例

用例一：从 API 文档到完整应用

产品团队希望基于 API 文档快速原型化应用，可编排这样的 Agent：

1. Firecrawl 块从 URL 抓取 API 文档；
2. Claude Code 块接收文档与提示词，例如 "Create a web app that demonstrates all the key features of this API"；
3. Claude Code 在沙箱内构建完整应用——HTML/CSS/JS 前端、完善的错误处理、真实 API 调用示例；
4. Files 输出配合 GitHub 类块把生成的代码推送到新仓库。

之后的迭代同样走图内闭环：把返回的 sandbox_id 与 session_id 传回 Claude Code 块，附上 "Add authentication" 或 "Improve the UI" 等精化请求，Claude Code 会在同一沙箱中直接修改既有文件。

用例二：多轮持续开发（官方文档 "Multi-turn Development"）

开发者用 Claude Code 分轮脚手架一个新项目，全程复用同一沙箱：

• 第 1 轮："Create a Python FastAPI project with user authentication"，设置 dispose_sandbox=false；
• 第 2 轮：将返回的 session_id + sandbox_id 填入输入，追加 "Add rate limiting middleware"；
• 第 3 轮：继续追加 "Add comprehensive tests"。

每一轮都在前一轮成果上累进，沙箱内的文件系统即长期记忆，无需重复搬移上下文。若沙箱因超时被回收，则在下一轮改传 conversation_history，让新沙箱通过系统提示词恢复对话脉络。

进阶提示与边界

综合官方文档与源码，使用时有几个值得注意的约束：

• timeout 只在新建沙箱时生效；重连既有沙箱会沿用创建时的原始超时（重连后也无法再延长）；
• session_id 与 sandbox_id 必须成对出现：有会话无沙箱会在执行前直接报错并引导你改用 conversation_history；
• dispose_sandbox=true（默认）下不要期待后续能拿到有效的 sandbox_id 回连；需要多轮对话务必关闭销毁开关并妥善保管两个 ID；
• 沙箱文件提取有扩展名白名单与 50MB 单文件上限，超大或未识别类型的产物不会被自动带回；
• Claude Code 的运行依赖沙箱内联网安装 npm 包，以及注入的 ANTHROPIC_API_KEY；两者分别由 E2B 与 Anthropic 凭据驱动。

继续深入

• 块实现全文：claude_code.py
• 官方块文档：claude_code.md
• 沙箱文件抽取/存储共享工具：sandbox_files.py
• 计费配置与 COST_USD 注册：block_cost_config.py
• 计费单元测试（150 积分/美元换算、成本缺失容错）：claude_code_cost_test.py
• 工作区 workspace:// 引用机制：workspace-media-architecture.md