Khoj 代码执行Code Execution能力解析基于 Terrarium 与 E2B 沙箱的本地自托管指南【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khojKhoj 的代码执行特性允许 AI 在受控沙箱中自动生成并运行 Python 代码从而补齐大模型在复杂定量计算、数据分析、图表生成与报告产出上的短板。本文以官方功能文档为核心结合仓库源码完整说明在自托管场景下如何用 Docker 部署本地 Terrarium 沙箱、如何切换到云端的 E2B 沙箱并深入讲解 Khoj 从推断该用代码工具到生成代码、注入输入文件、执行、回收结果的底层实现链路帮助你在自建 Khoj 服务上安全地启用这一能力。Khoj 为什么要做代码执行Khoj 可以生成并运行简单的 Python 代码尤其适合让 Khoj 帮你做数据分析、生成图表plots和报告。原因是 LLM 默认并不擅长复杂的量化任务——精确的数值计算、统计推导、公式求值容易出错而先生成代码、再把代码放到沙箱里真跑一遍的方式可以借助确定的程序执行结果来保证答案的准确性。从源码看这一能力被建模为一次对话命令ConversationCommandhelpers.py 中定义了Code code枚举对应的工具描述里也写明了其适用场景——运行 Python 脚本以解析信息、执行复杂计算、创建文档与图表见 helpers.py。代码执行在 api_chat.py 中作为 chat 流程的一个分支被触发。Khoj 会自动推断是否需要调用代码工具你也可以通过以下两种方式显式指定在对话中直接告诉 Khoj用代码工具code tool解决在聊天中输入/code斜杠命令强制走代码执行路径。关于如何用python代码块包裹生成的程序、如何执行并整理结果返回给用户可以继续阅读下文及官方 chat 功能文档的对应命令说明/code属于聊天命令体系的一部分。自托管代码沙箱的两种方案Khoj 的代码执行发生在沙箱里LLM 只负责写代码代码本身在一个隔离、用完即弃ephemeral的运行环境中执行。官方文档给出了两种沙箱后端方案托管位置网络访问可用 Python 库费用Terrarium Sandbox默认本机 Docker 容器无标准库 matplotlib/pandas/numpy/scipy/bs4/sympy 等免费E2B Sandbox可选E2B 远程云端有标准库 requests/matplotlib/pandas/numpy/scipy/bs4/sympy/einops/biopython/shapely/plotly/rdkit 等非免费方案一Terrarium 沙箱本地、免费Terrarium 来自 Cohere是一个可本地自托管self-host的代码沙箱实现。Khoj 官方文档推荐使用仓库根目录下的 docker-compose.yml 来自动化地拉起 Terrarium 沙箱服务如果你想手动启动也可以直接执行两条 Docker 命令docker pull ghcr.io/khoj-ai/terrarium:latest docker run -d -p 8080:8080 ghcr.io/khoj-ai/terrarium:latest如果希望直接从源码运行 Terrarium可参考 Terrarium 项目自身提供的开发development说明进行构建启动。Khoj 进程通过环境变量KHOJ_TERRARIUM_URL找到沙箱地址——默认值为SANDBOX_URL os.getenv(KHOJ_TERRARIUM_URL)见 run_code.py。在官方 docker-compose 中沙箱服务被命名为sandbox因此容器内通信地址即KHOJ_TERRARIUM_URLhttp://sandbox:8080。验证沙箱是否就绪启动后你可以用一条curlPOST 请求验证沙箱可用——它会求值一个最简单的 Python 表达式并返回结果curl -X POST -H Content-Type: application/json \ --url http://localhost:8080 \ --data-raw {code: 1 1} \ --no-buffer如果沙箱正常会返回包含执行结果例如输出2及 stdout/stderr的 JSON。这正是 Khoj 执行 Python 时所调用的同一个 HTTP 接口详见下文源码解读一节。docker-compose 一键启用仓库根目录的 docker-compose.yml 已内置 Terrarium 服务镜像为ghcr.io/khoj-ai/terrarium:latest并在 Khoj 服务中预设了指向它的KHOJ_TERRARIUM_URL环境变量因此执行docker compose up即可同时拉起 Khoj 与代码沙箱。方案二E2B 沙箱远程、更丰富的库支持E2Be2b.dev让 Khoj 把代码运行在远程但能力更全面的沙箱中支持更多 Python 第三方库在 Terrarium 的 Pyodide 环境基础上增加了 requests、plotly、rdkit、biopython 等见下方源码分析。需要说明的是E2B 是付费服务并非免费方案。切换到 E2B 沙箱只需三步在 E2B 的 dashboard 上生成一个 API key在运行 Khoj 服务器的那台机器上把该 key 设置为环境变量E2B_API_KEY如果使用官方 docker-compose.yml 部署需要在docker-compose.yml文件中取消注释并填写E2B_API_KEY这一行环境变量文件里已经预留了带注释的# - E2B_API_KEYyour_e2b_api_key条目。重启 Khoj 服务器使新的沙箱后端生效。从源码可以确认 E2B 生效的判断逻辑只要E2B_API_KEY环境变量非空即认为启用了 E2B 沙箱helpers.py该标志会同时影响工具描述、代码生成提示词中的沙箱上下文以及执行路径的选择详见下文。源码视角Khoj 的代码执行是怎么跑通的以官方文档的技术要点为主线我们结合 run_code.py 与对话主流程来还原完整链路。当一次对话解析出的命令集合中包含ConversationCommand.Code时api_chat.py 会以用户问题、聊天历史、检索到的笔记上下文、上传图片/文件等作为入参调用run_code()协程。第一步让模型生成 Python 代码generate_python_coderun_code会先向聊天模型发送为指令生成程序的状态事件然后调用generate_python_code()run_code.py。这一步的提示词模板在 prompts.py 中定义关键约束包括代码将在临时沙箱中运行提示词会显式告知模型当前沙箱是否具备网络访问权限{has_network_access}代码必须是自包含的无法访问当前对话只能读取程序自身产生的数据以及代码中显式引用到的用户文件路径图表、文档等需要展示给用户的产物必须写入{home_dir}即/home/user目录的文件中而不是直接显示禁止编写/运行任何危险、恶意或不可信的代码提示词同时注入当前日期、用户位置、用户名、Agent 人格personality上下文等信息。代码生成提示中会附加沙箱上下文用于告知模型环境里预装了哪些包prompts.pyE2B 模式标准库 requests、matplotlib、pandas、numpy、scipy、bs4、sympy、einops、biopython、shapely、plotly、rdkittorch、catboost、tensorflow、tkinter 不可用Terrarium 模式标准库 matplotlib、pandas、numpy、scipy、bs4、sympyrequests、torch、catboost、tensorflow、rdkit、tkinter 不可用。也就是说你在提示 Khoj 使用具体库如请求网络、做分子计算时能否成功取决于所选沙箱后端。模型返回后generate_python_code用正则(?:python)?\n(.*?)提取所有 markdown 代码块并拼接run_code.py若响应中没有任何 Python 代码块会直接抛出ValueError。第二步把用户文件注入沙箱生成的代码如果引用了用户的某个文件例如数据分析场景下让模型读笔记或上传的表格Khoj 会把用户的所有 FileObject 逐一比对只要文件名出现在生成的代码中就把该文件的原始文本以 base64 编码随代码一起提交并把代码中对完整路径的引用改写为纯文件名run_code.py。这就是文档所述数据分析和报表生成能基于你本地笔记/文档数据执行的原因。第三步选择沙箱并执行execute_sandboxed_python核心执行函数execute_sandboxed_pythonrun_code.py有明确的调度策略先用clean_code_python清洗代码然后若E2B_API_KEY已设置则优先走 E2B 分支ImportError 时回退 Terrarium否则走 Terrarium 分支。网络/连接类异常会按指数随机退避1~5 秒、最多 3 次的十重试tenacity策略自动重试。Terrarium 分支execute_terrarium向sandbox_url发 POSTbody 为{code: ..., files: [...]}超时 30 秒返回后会把其中的文本类输出文件text/*、.org、.md、.json从 base64 解码为可读文本。这与上文验证沙箱里手测的接口完全一致。E2B 分支execute_e2b通过e2b_code_interpreter.AsyncSandbox创建沙箱读取E2B_API_KEY模板默认值为DEFAULT_E2B_TEMPLATE也可用E2B_TEMPLATE环境变量覆盖随后并行上传输入文件、执行代码单次执行超时 60 秒执行完毕后对比/home/user目录文件快照识别程序新生成的文件并回读——图片类png/jpeg/jpg/svg以 base64 二进制形式返回以用于行内展示文本类返回可读内容stdout/stderr 与success标志一并打包。第四步结果回填与失败兜底run_code汇总后会向调用方产出{instructions: {code: ..., results: ...}}并依据 prompts.py 的code_executed_context提示词让模型基于真实的代码执行结果组织最终回答。若执行超时如 Terrarium 端超过 30 秒Khoj 还会主动向沙箱的/stop端点发 GET 请求以中止沙箱再抛出带错误说明的ValueError上层在 api_chat.py 捕获后记录日志并尝试不带代码结果继续作答避免一次执行失败导致整个会话中断。实战建议与注意事项默认免费路径是本地 Terrarium只要不设置E2B_API_KEYKhoj 就使用KHOJ_TERRARIUM_URL默认http://sandbox:8080见 docker-compose.yml指向的本地沙箱成本最低、数据不出内网。需要联网或更多三方库时再上 E2BTerrarium 沙箱没有网络访问权限可用包也较少若你的分析需要 requests 抓取数据或 rdkit/plotly 等重型库需配置E2B_API_KEY并在 docker-compose 中取消注释对应环境变量行后重启 Khoj。让模型生成图表/文档时的写法提示模型时尽量让它把 matplotlib 图、csv/报告写到/home/user目录Khoj 会自动识别并回收这些输出文件回传展示不要试图在代码里直接显示图片。安全边界无论哪个沙箱代码生成提示与工具描述都强制要求不得运行恶意/不受信任的代码且沙箱本身隔离、用完即弃本地自托管场景下建议将沙箱端口仅暴露给 Khoj 服务使用。小结Khoj 的代码执行能力本质上是一个LLM 写代码 隔离沙箱执行 结果回传再作答的闭环官方文档给出的自托管方案中docker-compose.yml 内置的 Terrarium 是零成本默认项E2B 则面向需要网络与更丰富 Python 生态的高级场景。通过 run_code.py 的实现可以看到代码生成提示词、沙箱环境说明、输入文件注入、超时/重试兜底都被精细地工程化这使得 Khoj 在处理精确计算、数据可视化与报告类问题时能够显著优于纯靠模型心算的问答方式。【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khoj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Khoj 代码执行（Code Execution）能力解析：基于 Terrarium 与 E2B 沙箱的本地自托管指南
Khoj 代码执行Code Execution能力解析基于 Terrarium 与 E2B 沙箱的本地自托管指南【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khojKhoj 的代码执行特性允许 AI 在受控沙箱中自动生成并运行 Python 代码从而补齐大模型在复杂定量计算、数据分析、图表生成与报告产出上的短板。本文以官方功能文档为核心结合仓库源码完整说明在自托管场景下如何用 Docker 部署本地 Terrarium 沙箱、如何切换到云端的 E2B 沙箱并深入讲解 Khoj 从推断该用代码工具到生成代码、注入输入文件、执行、回收结果的底层实现链路帮助你在自建 Khoj 服务上安全地启用这一能力。Khoj 为什么要做代码执行Khoj 可以生成并运行简单的 Python 代码尤其适合让 Khoj 帮你做数据分析、生成图表plots和报告。原因是 LLM 默认并不擅长复杂的量化任务——精确的数值计算、统计推导、公式求值容易出错而先生成代码、再把代码放到沙箱里真跑一遍的方式可以借助确定的程序执行结果来保证答案的准确性。从源码看这一能力被建模为一次对话命令ConversationCommandhelpers.py 中定义了Code code枚举对应的工具描述里也写明了其适用场景——运行 Python 脚本以解析信息、执行复杂计算、创建文档与图表见 helpers.py。代码执行在 api_chat.py 中作为 chat 流程的一个分支被触发。Khoj 会自动推断是否需要调用代码工具你也可以通过以下两种方式显式指定在对话中直接告诉 Khoj用代码工具code tool解决在聊天中输入/code斜杠命令强制走代码执行路径。关于如何用python代码块包裹生成的程序、如何执行并整理结果返回给用户可以继续阅读下文及官方 chat 功能文档的对应命令说明/code属于聊天命令体系的一部分。自托管代码沙箱的两种方案Khoj 的代码执行发生在沙箱里LLM 只负责写代码代码本身在一个隔离、用完即弃ephemeral的运行环境中执行。官方文档给出了两种沙箱后端方案托管位置网络访问可用 Python 库费用Terrarium Sandbox默认本机 Docker 容器无标准库 matplotlib/pandas/numpy/scipy/bs4/sympy 等免费E2B Sandbox可选E2B 远程云端有标准库 requests/matplotlib/pandas/numpy/scipy/bs4/sympy/einops/biopython/shapely/plotly/rdkit 等非免费方案一Terrarium 沙箱本地、免费Terrarium 来自 Cohere是一个可本地自托管self-host的代码沙箱实现。Khoj 官方文档推荐使用仓库根目录下的 docker-compose.yml 来自动化地拉起 Terrarium 沙箱服务如果你想手动启动也可以直接执行两条 Docker 命令docker pull ghcr.io/khoj-ai/terrarium:latest docker run -d -p 8080:8080 ghcr.io/khoj-ai/terrarium:latest如果希望直接从源码运行 Terrarium可参考 Terrarium 项目自身提供的开发development说明进行构建启动。Khoj 进程通过环境变量KHOJ_TERRARIUM_URL找到沙箱地址——默认值为SANDBOX_URL os.getenv(KHOJ_TERRARIUM_URL)见 run_code.py。在官方 docker-compose 中沙箱服务被命名为sandbox因此容器内通信地址即KHOJ_TERRARIUM_URLhttp://sandbox:8080。验证沙箱是否就绪启动后你可以用一条curlPOST 请求验证沙箱可用——它会求值一个最简单的 Python 表达式并返回结果curl -X POST -H Content-Type: application/json \ --url http://localhost:8080 \ --data-raw {code: 1 1} \ --no-buffer如果沙箱正常会返回包含执行结果例如输出2及 stdout/stderr的 JSON。这正是 Khoj 执行 Python 时所调用的同一个 HTTP 接口详见下文源码解读一节。docker-compose 一键启用仓库根目录的 docker-compose.yml 已内置 Terrarium 服务镜像为ghcr.io/khoj-ai/terrarium:latest并在 Khoj 服务中预设了指向它的KHOJ_TERRARIUM_URL环境变量因此执行docker compose up即可同时拉起 Khoj 与代码沙箱。方案二E2B 沙箱远程、更丰富的库支持E2Be2b.dev让 Khoj 把代码运行在远程但能力更全面的沙箱中支持更多 Python 第三方库在 Terrarium 的 Pyodide 环境基础上增加了 requests、plotly、rdkit、biopython 等见下方源码分析。需要说明的是E2B 是付费服务并非免费方案。切换到 E2B 沙箱只需三步在 E2B 的 dashboard 上生成一个 API key在运行 Khoj 服务器的那台机器上把该 key 设置为环境变量E2B_API_KEY如果使用官方 docker-compose.yml 部署需要在docker-compose.yml文件中取消注释并填写E2B_API_KEY这一行环境变量文件里已经预留了带注释的# - E2B_API_KEYyour_e2b_api_key条目。重启 Khoj 服务器使新的沙箱后端生效。从源码可以确认 E2B 生效的判断逻辑只要E2B_API_KEY环境变量非空即认为启用了 E2B 沙箱helpers.py该标志会同时影响工具描述、代码生成提示词中的沙箱上下文以及执行路径的选择详见下文。源码视角Khoj 的代码执行是怎么跑通的以官方文档的技术要点为主线我们结合 run_code.py 与对话主流程来还原完整链路。当一次对话解析出的命令集合中包含ConversationCommand.Code时api_chat.py 会以用户问题、聊天历史、检索到的笔记上下文、上传图片/文件等作为入参调用run_code()协程。第一步让模型生成 Python 代码generate_python_coderun_code会先向聊天模型发送为指令生成程序的状态事件然后调用generate_python_code()run_code.py。这一步的提示词模板在 prompts.py 中定义关键约束包括代码将在临时沙箱中运行提示词会显式告知模型当前沙箱是否具备网络访问权限{has_network_access}代码必须是自包含的无法访问当前对话只能读取程序自身产生的数据以及代码中显式引用到的用户文件路径图表、文档等需要展示给用户的产物必须写入{home_dir}即/home/user目录的文件中而不是直接显示禁止编写/运行任何危险、恶意或不可信的代码提示词同时注入当前日期、用户位置、用户名、Agent 人格personality上下文等信息。代码生成提示中会附加沙箱上下文用于告知模型环境里预装了哪些包prompts.pyE2B 模式标准库 requests、matplotlib、pandas、numpy、scipy、bs4、sympy、einops、biopython、shapely、plotly、rdkittorch、catboost、tensorflow、tkinter 不可用Terrarium 模式标准库 matplotlib、pandas、numpy、scipy、bs4、sympyrequests、torch、catboost、tensorflow、rdkit、tkinter 不可用。也就是说你在提示 Khoj 使用具体库如请求网络、做分子计算时能否成功取决于所选沙箱后端。模型返回后generate_python_code用正则(?:python)?\n(.*?)提取所有 markdown 代码块并拼接run_code.py若响应中没有任何 Python 代码块会直接抛出ValueError。第二步把用户文件注入沙箱生成的代码如果引用了用户的某个文件例如数据分析场景下让模型读笔记或上传的表格Khoj 会把用户的所有 FileObject 逐一比对只要文件名出现在生成的代码中就把该文件的原始文本以 base64 编码随代码一起提交并把代码中对完整路径的引用改写为纯文件名run_code.py。这就是文档所述数据分析和报表生成能基于你本地笔记/文档数据执行的原因。第三步选择沙箱并执行execute_sandboxed_python核心执行函数execute_sandboxed_pythonrun_code.py有明确的调度策略先用clean_code_python清洗代码然后若E2B_API_KEY已设置则优先走 E2B 分支ImportError 时回退 Terrarium否则走 Terrarium 分支。网络/连接类异常会按指数随机退避1~5 秒、最多 3 次的十重试tenacity策略自动重试。Terrarium 分支execute_terrarium向sandbox_url发 POSTbody 为{code: ..., files: [...]}超时 30 秒返回后会把其中的文本类输出文件text/*、.org、.md、.json从 base64 解码为可读文本。这与上文验证沙箱里手测的接口完全一致。E2B 分支execute_e2b通过e2b_code_interpreter.AsyncSandbox创建沙箱读取E2B_API_KEY模板默认值为DEFAULT_E2B_TEMPLATE也可用E2B_TEMPLATE环境变量覆盖随后并行上传输入文件、执行代码单次执行超时 60 秒执行完毕后对比/home/user目录文件快照识别程序新生成的文件并回读——图片类png/jpeg/jpg/svg以 base64 二进制形式返回以用于行内展示文本类返回可读内容stdout/stderr 与success标志一并打包。第四步结果回填与失败兜底run_code汇总后会向调用方产出{instructions: {code: ..., results: ...}}并依据 prompts.py 的code_executed_context提示词让模型基于真实的代码执行结果组织最终回答。若执行超时如 Terrarium 端超过 30 秒Khoj 还会主动向沙箱的/stop端点发 GET 请求以中止沙箱再抛出带错误说明的ValueError上层在 api_chat.py 捕获后记录日志并尝试不带代码结果继续作答避免一次执行失败导致整个会话中断。实战建议与注意事项默认免费路径是本地 Terrarium只要不设置E2B_API_KEYKhoj 就使用KHOJ_TERRARIUM_URL默认http://sandbox:8080见 docker-compose.yml指向的本地沙箱成本最低、数据不出内网。需要联网或更多三方库时再上 E2BTerrarium 沙箱没有网络访问权限可用包也较少若你的分析需要 requests 抓取数据或 rdkit/plotly 等重型库需配置E2B_API_KEY并在 docker-compose 中取消注释对应环境变量行后重启 Khoj。让模型生成图表/文档时的写法提示模型时尽量让它把 matplotlib 图、csv/报告写到/home/user目录Khoj 会自动识别并回收这些输出文件回传展示不要试图在代码里直接显示图片。安全边界无论哪个沙箱代码生成提示与工具描述都强制要求不得运行恶意/不受信任的代码且沙箱本身隔离、用完即弃本地自托管场景下建议将沙箱端口仅暴露给 Khoj 服务使用。小结Khoj 的代码执行能力本质上是一个LLM 写代码 隔离沙箱执行 结果回传再作答的闭环官方文档给出的自托管方案中docker-compose.yml 内置的 Terrarium 是零成本默认项E2B 则面向需要网络与更丰富 Python 生态的高级场景。通过 run_code.py 的实现可以看到代码生成提示词、沙箱环境说明、输入文件注入、超时/重试兜底都被精细地工程化这使得 Khoj 在处理精确计算、数据可视化与报告类问题时能够显著优于纯靠模型心算的问答方式。【免费下载链接】khojYour AI second brain. Self-hostable. Get answers from the web or your docs. Build custom agents, schedule automations, do deep research. Turn any online or local LLM into your personal, autonomous AI (gpt, claude, gemini, llama, qwen, mistral). Get started - free.项目地址: https://gitcode.com/GitHub_Trending/kh/khoj创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考