沙箱 Skill Sandbox Runtime 跑 WeKnora，TaoToken 给 Agent 供 Key

1. Skill Sandbox Runtime 跑 WeKnora：先解决模型入口，再解决持续工作空间

WeKnora 的 Skill Sandbox Runtime 不是“多一个代码执行器”这么简单。它给每个聊天 Session 挂了一个持续存在的工作空间：Agent 可以检索企业知识库、调用 Skill、执行 Shell、读写文件、处理用户上传的 Excel/PDF，最后把生成的文件作为结果返回。对 Agent 运行时工程师来说，这套东西最值得盯住的是“状态”和“隔离”：状态要跨轮次保留，隔离要保证不同会话、不同用户、不同任务不互相污染。

但要让这条链路真正跑起来，模型入口必须先稳定。我的做法是去 TaoToken 拿 Key，模型侧统一填https://taotoken.net/api，再让 WeKnora 的 ReAct Agent 和 Skill Sandbox Runtime 共用这个入口。TaoToken 官网入口在这里：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weknora_sandbox。本文不写新闻评论，直接给可复现产出：一份 Skill Sandbox Runtime 配置片段，一份 Agent 执行结果对照，以及 Claude Code、Codex、CC Switch 在 TaoToken 下的配置边界。

如果你正在做的是企业知识库 Agent，而不是单纯 PDF 问答，那么大概率会遇到三个具体问题：第一，模型调用走哪个 Base URL、Key 放在哪层；第二，沙箱后端选 Docker、E2B 还是 Cube；第三，Agent 执行完 Python 后，生成的文件怎么回到会话里。下面按运行时工程师的视角拆开。

2. 为什么 Agent 运行时需要 Skill Sandbox Runtime

传统 RAG 的典型链路是：上传文档、解析、切块、向量化、检索、拼上下文、交给模型回答。它能解决“知识在哪里”，但解决不了“知识怎么被使用”。比如用户上传一份 Excel，问“按照公司差旅补贴规则重新计算，并给我一份报告”，纯 RAG 最多召回规则片段，然后让模型口算。模型可能算对，也可能漏行、错列、把表头当数据。企业场景里，这种不确定性不能靠 prompt 兜底。

WeKnora 把能力往 Agent 方向延伸后，链路变成：ReAct Agent 先理解任务，再检索企业知识库，找到差旅补贴规则；然后调用 Skill，在沙箱里运行 Python；沙箱读取用户附件，执行 pandas 计算，生成新的 Excel；最后把文件路径和摘要返回给 Agent。Agent 不需要把整个 Excel 塞进上下文，也不需要让模型手算每一行。模型负责规划、检索、解释，沙箱负责确定性执行。

这就是 Skill Sandbox Runtime 的价值：它把“模型推理”和“工具执行”分开。模型侧要稳定、可替换、可计费；沙箱侧要隔离、可持久化、可审计。WeKnora 支持 Docker、E2B、Cube 三种后端，正好对应不同运行时环境：

• Docker：本地或内网部署最直接，适合已有容器平台的团队。缺点是要处理 Docker socket 权限、镜像预热、资源限制。
• E2B：云端沙箱，适合不想维护容器调度的团队。要注意网络策略、数据出域、附件上传路径。
• Cube：偏隔离和轻量级执行，适合对启动速度和资源占用敏感的场景。具体能力要按你用的版本来评估。

从我的经验看，刚开始验证链路时优先用 Docker。因为你能看到容器、卷、日志、退出码，排障路径最短。等 Skill 稳定了，再考虑 E2B 或 Cube 做弹性。无论选哪个后端，模型侧都建议统一走 TaoToken。原因不是“额度”两个字，而是运行时需要可替换的模型入口：今天用 Claude 做规划和总结，明天换一个更便宜的模型做检索改写，Base URL 和 Key 管理方式不应该跟着变。

WeKnora 还补了 Wiki Mode、长期记忆、知识图谱、MCP Server、CLI 和 API。这些能力组合起来，Agent 不只是“知道公司文档”，还逐步记住用户是谁、关注什么、做过哪些任务。对运行时工程师来说，这意味着会话状态、记忆写入、沙箱工作空间、文件生命周期要一起设计。下面先解决 Key 和 Base URL。

3. 从 TaoToken 取 Key：三步拿到 Agent 的模型入口

第一步，打开 TaoToken 官网注册或登录：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weknora_key。

第二步，先在模型对话里做一次最小验证，确认模型可用：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weknora_chat。这一步不是走过场。运行时排障最怕把“模型不可用”误判成“沙箱坏了”。先用对话确认 Key、Base URL、模型名三件事。

第三步，到控制台创建 API Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_keys。创建后复制 Key，后面用YOUR_API_KEY占位。

在 Agent 运行时里，建议把 Key 放在环境变量或密钥管理里，不要写进代码仓库。基础环境变量如下：

# TaoToken 模型入口 export TAOTOKEN_API_KEY=YOUR_API_KEY export OPENAI_API_KEY=YOUR_API_KEY export OPENAI_BASE_URL=https://taotoken.net/api # 如果某个组件使用 Anthropic 兼容协议，再单独设置 export ANTHROPIC_BASE_URL=https://taotoken.net/api export ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY

注意两点。

第一，OPENAI_BASE_URL和ANTHROPIC_BASE_URL都填https://taotoken.net/api，不要加 UTM 参数。UTM 是给官网链接做来源标记的，工具配置只认干净的 Base URL。

第二，不要混用协议。OpenAI 兼容客户端用OPENAI_*，Anthropic 兼容客户端用ANTHROPIC_*。后面讲 Codex 时会单独用config.toml，不会把ANTHROPIC_*套过去。

可以在本地先用 curl 验证模型入口：

curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role": "user", "content": "只回复 pong"} ] }'

如果返回正常，说明 Key 和 Base URL 没问题。接下来把 WeKnora 的模型配置指向同一个入口。

4. WeKnora + Skill Sandbox Runtime 最小配置

WeKnora 推荐用 Docker Compose 部署。提前准备 Docker、Docker Compose 和 Git，然后克隆项目。这里不重复官方命令，重点放在运行时配置。不同版本的变量名可能不同，以你拉取下来的.env.example或config.yaml为准。核心映射关系是三类：模型 Base URL、API Key、沙箱后端。

在项目根目录准备.env，把模型侧和沙箱侧分开写：

# ===== 模型侧：统一走 TaoToken ===== MODEL_PROVIDER=openai-compatible OPENAI_API_BASE=https://taotoken.net/api OPENAI_API_KEY=YOUR_API_KEY MODEL_NAME=gpt-4o-mini # 如果 WeKnora 的某些 Agent 组件走 Anthropic 兼容协议 ANTHROPIC_BASE_URL=https://taotoken.net/api ANTHROPIC_AUTH_TOKEN=YOUR_API_KEY ANTHROPIC_MODEL=claude-sonnet-4-5 # ===== Skill Sandbox Runtime ===== SKILL_SANDBOX_ENABLED=true SANDBOX_BACKEND=docker SANDBOX_IMAGE=python:3.11-slim SANDBOX_WORKSPACE_DIR=/data/weknora/sandbox SANDBOX_PERSIST=true SANDBOX_TIMEOUT=600 SANDBOX_NETWORK=none SANDBOX_MEMORY=512m SANDBOX_CPU=1.0

解释几个关键项：

• SANDBOX_BACKEND=docker：先用本地 Docker 跑通，排障最直接。
• SANDBOX_IMAGE=python:3.11-slim：基础镜像。如果你要跑 pandas、openpyxl，可以直接用，也可以在自定义镜像里预装。
• SANDBOX_WORKSPACE_DIR：工作空间根目录。每个 Session 最好有独立子目录，例如sess_8f3a。
• SANDBOX_PERSIST=true：跨轮次保留文件。没有这个，Agent 第二轮就找不到上一轮生成的文件。
• SANDBOX_NETWORK=none：默认不给沙箱外网。需要装包时再按需开网络，或者预装依赖。
• SANDBOX_TIMEOUT=600：任务超时。模型调用超时和沙箱执行超时要分开设置，否则排障时分不清是谁超时。

Compose 层要把工作空间和 Docker socket 挂进去。示例：

services: weknora: image: weknora/weknora:latest ports: - "80:80" env_file: - .env volumes: - ./data:/data - /var/run/docker.sock:/var/run/docker.sock # 如果项目拆分出了 sandbox-runtime 服务，按实际 compose 文件调整 sandbox-runtime: image: weknora/sandbox-runtime:latest env_file: - .env volumes: - ./data/weknora/sandbox:/data/weknora/sandbox - /var/run/docker.sock:/var/run/docker.sock depends_on: - weknora

启动：

docker compose up -d docker compose logs -f weknora

浏览器访问http://localhost进入 Web UI。如果沙箱启动失败，优先查三件事：Docker daemon 是否运行、当前用户是否有 Docker socket 权限、SANDBOX_WORKSPACE_DIR是否可写。不要一上来就改模型配置。模型入口和沙箱运行时是两条排障线，先分开验证。

5. 写一个能在沙箱里跑的 Skill：Excel 差旅补贴分析

为了验证 Skill Sandbox Runtime 是否真的在工作，我构造一个具体任务：用户上传expenses.xlsx，问“按企业差旅补贴规则计算每位员工的补贴，并生成报告文件”。Agent 需要先检索知识库里的规则，再调用 Skill 在沙箱里跑 Python。

目录结构可以这样放：

skills/ travel-subsidy/ skill.yaml run.py requirements.txt

skill.yaml描述 Skill 的输入输出：

name: travel-subsidy description: 根据企业差旅规则计算员工补贴并生成 Excel 报告 runtime: python entrypoint: run.py inputs: - name: expense_file type: file required: true - name: policy_query type: string default: "差旅补贴标准" outputs: - name: report type: file path: output/report.xlsx

requirements.txt：

pandas openpyxl

run.py是沙箱里真正执行的脚本：

import os from pathlib import Path import pandas as pd def main(): # 沙箱工作空间内，上传附件通常会被映射到 input/ 或环境变量指定路径 expense_file = os.environ.get("EXPENSE_FILE", "input/expenses.xlsx") output_dir = Path("output") output_dir.mkdir(parents=True, exist_ok=True) df = pd.read_excel(expense_file) # 示例规则：一线城市 500/天，二线 350/天，其他 200/天 # 真实场景中，这些规则应由 Agent 从 WeKnora 知识库检索后传入 city_rate = { "北京": 500, "上海": 500, "广州": 500, "深圳": 500, "杭州": 350, "成都": 350, } df["标准"] = df["城市"].map(city_rate).fillna(200) df["补贴"] = df["天数"] * df["标准"] total = int(df["补贴"].sum()) report = output_dir / "report.xlsx" df.to_excel(report, index=False) print(f"rows={len(df)}") print(f"total_subsidy={total}") print(f"report={report}") if __name__ == "__main__": main()

然后在 WeKnora 里上传 Excel，输入任务：

请从企业知识库中找到差旅补贴标准，调用 travel-subsidy Skill， 读取我上传的 expenses.xlsx，计算补贴，并返回 report.xlsx。

预期执行链路：

1. ReAct Agent 解析任务，识别需要检索知识库和调用 Skill。
2. 检索模块从 WeKnora 知识库召回差旅规则。
3. Agent 调用travel-subsidy，把附件路径、规则参数传给沙箱。
4. Skill Sandbox Runtime 启动容器，挂载 Session 工作空间。
5. run.py读取 Excel，执行 pandas 计算，写出output/report.xlsx。
6. Agent 收到 stdout 和文件路径，把报告作为附件返回。

这里最容易出问题的是文件路径。建议在运行时日志里打印工作空间绝对路径，并确保SANDBOX_PERSIST=true。否则第一轮生成的文件，第二轮 Agent 就找不到了。

6. Agent 执行结果对照：无沙箱 vs 有沙箱

为了判断 Skill Sandbox Runtime 是否值得上，我做了一组对照。同一个 Excel、同一个问题，分别跑纯 ReAct 检索和带沙箱 Skill 的流程。

| 环节 | 无 Skill Sandbox Runtime | 有 Skill Sandbox Runtime | | 知识检索 | 能召回规则片段 | 能召回规则片段 | | 计算方式 | 模型在上下文里口算 | 沙箱内 pandas 逐行计算 | | 附件读取 | 通常只能把文本塞进上下文 | 直接读 Excel 原始单元格 | | 结果文件 | 只能返回文字 | 返回report.xlsx下载 | | 可复现性 | 同一问题多次运行可能不一致 | 同一输入输出一致 | | 审计 | 只有对话记录 | 有 Shell stdout、退出码、文件路径 | | 多轮会话 | 文件容易丢 | Session 工作空间持久 | | 复杂任务 | 行数一多容易漏 | 可处理数千行 |

沙箱执行日志大致如下：

[retrieval] found 3 chunks from policy/travel.md [skill] travel-subsidy started [sandbox] backend=docker image=python:3.11-slim workspace=/data/weknora/sandbox/sess_8f3a [stdout] rows=42 [stdout] total_subsidy=38600 [stdout] report=output/report.xlsx [result] file attached: report.xlsx (8.7 KB)

对照结论很直接：如果任务只要求“回答文档里写了什么”，纯 RAG 够用。如果任务要求“按照规则处理文件、计算、生成新文件”，没有沙箱的 Agent 会在确定性和文件交付上卡住。Skill Sandbox Runtime 补的正是这一层。

对运行时工程师来说，还要关注资源限制。SANDBOX_MEMORY=512m、SANDBOX_CPU=1.0、SANDBOX_TIMEOUT=600是起步值。真实任务里要按 Excel 行数、pandas 内存占用、生成文件大小调整。不要让沙箱无限制使用宿主机资源。

7. 把 Claude Code、Codex、CC Switch 接到 TaoToken

WeKnora 的一个重要方向是充当其他 Agent 的外部知识层。它提供 API、CLI 和 MCP Server，Claude Code、DeepSeek Harness 或自研 Agent 可以搜索 WeKnora 知识库、读取完整文档，或者调用 RAG / ReAct 流程。模型供应商则可以统一走 TaoToken。

先看 Claude Code。它的配置入口是settings.json，使用ANTHROPIC_*环境变量：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY", "ANTHROPIC_MODEL": "claude-sonnet-4-5", "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5" } }

如果你的 Claude Code 版本使用 API Key 而不是 auth token，可以把ANTHROPIC_AUTH_TOKEN换成ANTHROPIC_API_KEY。不要同时写两个值不一致的 Key。Base URL 保持https://taotoken.net/api，不要带 UTM。

再看 Codex。Codex 不使用ANTHROPIC_*，它用config.toml。配置方式如下：

model = "gpt-5-codex" model_provider = "taotoken" [model_providers.taotoken] name = "TaoToken" base_url = "https://taotoken.net/api" env_key = "TAOTOKEN_API_KEY" wire_api = "chat"

对应环境变量：

export TAOTOKEN_API_KEY=YOUR_API_KEY

这样 Codex 会从TAOTOKEN_API_KEY读取 Key，从https://taotoken.net/api走模型请求。注意，不要把 Claude Code 的ANTHROPIC_*复制到 Codex 配置里，两者协议和字段不同，混用会直接导致 401 或 404。

如果你用 CC Switch 管理多套配置，可以把它理解成“三件套”的切换器：供应商名称、Base URL、API Key。落到 Claude Code 上，三件套就是ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL对应的配置组；落到 Codex 上，三件套是model_provider、base_url、env_key对应的config.toml段。CC Switch 只负责切换，不负责把 Anthropic 协议翻译成 OpenAI 协议。所以配置边界要自己守住。

如果要把 WeKnora 作为外部知识层挂给 Claude Code，可以单独配 MCP。注意这里连的是 WeKnora 的 MCP Server，不是模型 Key。模型 Key 仍然走 TaoToken。

{ "mcpServers": { "weknora": { "command": "weknora", "args": ["mcp", "serve"], "env": { "WEKNORA_API_BASE": "http://localhost:8080", "WEKNORA_API_KEY": "YOUR_WEKNORA_KEY" } } } }

生产环境里不要把 MCP 或 Agent 直连到 Oracle、MySQL 等生产库。让 WeKnora 通过受控 API 暴露知识检索，SQL 和命令由读者在本地或隔离环境执行。运行时边界要清楚：模型侧走 TaoToken，知识侧走 WeKnora，执行侧走 Skill Sandbox Runtime。

8. 常见排障与验收清单

排障时按链路拆，不要一锅炖。

401 / 403：Key 错误或没带上。去 TaoToken 控制台重新创建：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_troubleshoot。确认环境变量名和工具要求一致。

404：Base URL 路径不对。工具配置填https://taotoken.net/api，不要填官网首页，也不要带 UTM。OpenAI 兼容客户端通常会自动补/v1。

模型名不存在：先到模型对话确认可用模型：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weknora_model。Codex、Claude Code、WeKnora 的模型名可能不同，不要硬编码一个名字到处用。

沙箱启动失败：检查 Docker daemon、socket 权限、镜像是否可拉取。SANDBOX_NETWORK=none时，容器内不能临时pip install，要预装依赖或自定义镜像。

文件不持久：确认SANDBOX_PERSIST=true，确认SANDBOX_WORKSPACE_DIR挂载到了宿主机目录。检查 Session ID 是否变化。

多会话串数据：每个 Session 使用独立工作空间。不要多个 Session 共用一个目录。

超时：模型超时和沙箱超时分开配。SANDBOX_TIMEOUT=600是沙箱执行上限，模型请求超时在模型客户端侧设置。

验收清单可以这样列：

[ ] TaoToken Key 可用，模型对话返回正常 [ ] WeKnora 模型侧 Base URL = https://taotoken.net/api [ ] Skill Sandbox Runtime 后端启动成功 [ ] Session 工作空间可写、可持久化 [ ] Skill 能在沙箱内执行 Python [ ] 上传 Excel 后能生成 report.xlsx [ ] 第二轮对话仍能引用上一轮文件 [ ] Claude Code 使用 ANTHROPIC_* 配置 [ ] Codex 使用 config.toml，未混用 ANTHROPIC_* [ ] 沙箱未直连生产库，SQL 由本地或隔离环境执行

9. 推荐接入路径

如果你还没拿到 Key，建议按这个顺序走：

1. 先到模型对话验证模型可用：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weknora_cta_chat
2. 需要长期跑 Agent、Coding Agent 或沙箱任务，看 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=weknora_cta_plan
3. 创建 API Key，填入YOUR_API_KEY：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_cta_keys
4. Claude Code 配置参考官方文档：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=weknora_cta_claudecode

WeKnora 把企业知识库从“能被检索”推进到“能被 Agent 使用”，Skill Sandbox Runtime 则把“能回答”推进到“能执行、能产出文件”。运行时工程师要做的，是把模型入口、知识入口、执行入口三者拆清楚：模型入口走 TaoToken，Base URL 填https://taotoken.net/api；知识入口走 WeKnora 的 API、CLI 或 MCP Server；执行入口走 Skill Sandbox Runtime，配置好 Docker/E2B/Cube 后端和持久工作空间。这样，无论上层是 Claude Code、Codex 还是自研 Agent，底层知识层和沙箱运行时都可以复用。TaoToken 官网入口再放一次，方便直接取 Key：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weknora_final。