底座 WeKnora 管知识，TaoToken 替 ReAct Agent 管 Token-平芜编程栈

1. 从 WeKnora 的 ReAct 链路看：知识底座与模型 Token 要分开管

如果你正在把企业文档、Wiki、飞书、Notion、GitLab 里的资料接进 AI 工作流，大概率会遇到一个很具体的问题：知识检索已经跑通了，但 ReAct Agent 一旦进入多轮循环，模型调用就开始不稳定。尤其是 WeKnora 这类把 RAG、ReAct、MCP、Skills、代码沙箱、长期记忆和自动 Wiki 串在一起的项目，知识层和执行层是打通的，模型层却经常被当成一个全局变量随便填。结果就是：检索引擎没问题，Rerank 没问题，沙箱也能跑，但 Agent 在第三、第四轮 tool_call 时突然 401、429，或者返回的 function call 结构解析失败，整条链路断在模型网关这一层。

WeKnora 的定位很清晰：它不是“上传 PDF 然后聊天”的简单 RAG，而是企业知识底座。底层做文档解析、自适应分块、向量检索与 BM25 混合搜索、Rerank；上层接 ReAct Agent，让模型可以围绕一个问题反复检索知识库、调用 MCP 和 Skills、进入 Docker/E2B/Cube 沙箱执行 Shell 和 Python、读写文件，并把生成结果作为附件返回。再加上 Wiki Mode、知识图谱、跨会话长期记忆，它实际上把企业知识从“静态文档库”升级成了“Agent 可调用的知识基础设施”。也正因为这样，模型 Token 的管理不能继续散落在各个 Harness 里。你可以去 TaoToken 官网看一下 Key 和模型接入方式：https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_agent 。本文以 Agent 基础设施开发者的视角，把 WeKnora 当作知识底座，把 TaoToken 当作 ReAct Agent 的模型 Token 层，给出一套可复现的模型参数与调用链路对照，重点不是复述项目新闻，而是让你能照着改配置、排错误、跑通链路。

先统一一个原则：知识底座管“查什么”，ReAct Agent 管“怎么查、怎么执行”，TaoToken 管“模型调用用什么 Key、走哪个 Base URL、消耗多少 Token”。这三层解耦之后，企业内部同时跑 Claude Code、Codex、自研 Agent 或 DeepSeek Harness 时，底层可以共享同一个 WeKnora 知识层，上层可以按任务切换模型，而不需要把 API Key 和供应商配置写死在每个工具里。

2. 部署 WeKnora：先把知识底座跑起来

WeKnora 官方推荐的方式是 Docker Compose。你需要提前准备 Docker、Docker Compose 和 Git。具体命令不需要照抄某篇新闻稿，按下面顺序执行即可：

# 1. 从 WeKnora 官方仓库克隆项目 git clone <WeKnora 官方仓库地址> cd WeKnora # 2. 复制环境变量模板 cp .env.example .env # 3. 启动服务 docker compose up -d # 4. 查看容器状态 docker compose ps

启动完成后，浏览器访问http://localhost进入 Web UI。如果你是在远程服务器上部署，把 localhost 换成服务器 IP，并确认安全组或防火墙放行对应端口。第一次进入后，先不要急着上传大量文档，建议用一份 10 页以内的 PDF 和一份 Excel 做最小验证，确认文档解析、分块、向量化、检索、Rerank 这条链路正常。

接下来是模型配置。WeKnora 支持多种模型供应商，接入 OpenAI 兼容接口时，核心参数只有四个：

# 概念配置，具体字段名以 WeKnora 当前版本为准 model: provider: openai-compatible base_url: https://taotoken.net/api api_key: YOUR_API_KEY model: your-model-name

这里有两个容易踩坑的点。第一，Base URL 用https://taotoken.net/api，不要自己脑补成https://taotoken.net/api/v1再填到“基础地址”里；很多 OpenAI 兼容客户端会自动补/v1/chat/completions，你多写一层就会变成/api/v1/v1/...，直接 404 或 401。第二，API Key 不要写死在代码仓库里，用环境变量或 WeKnora 的密钥管理功能，Key 占位符统一写YOUR_API_KEY。如果你还没有 Key，可以在 TaoToken 控制台创建：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_key 。

WeKnora 的 Skill Sandbox Runtime 支持 Docker、E2B 和 Cube 三种后端。对本地开发来说，先用 Docker 后端最容易复现。每个聊天 Session 可以有一个持续存在的工作空间，Agent 不仅能检索知识，还能执行 Shell、读写文件、处理用户上传的附件。比如用户上传一份 Excel，Agent 先从知识库中找到业务规则，再在沙箱里运行 Python 做数据分析，最后生成新的报告文件。这个过程中，模型只负责决定“调用哪个 Skill、传什么参数”，真正的执行发生在沙箱里，所以不要让模型直连生产数据库，也不要把生产库凭证塞进 MCP 配置。SQL 和命令应该由读者在本地或隔离环境执行，Agent 只拿脱敏后的结果。

3. ReAct Agent 模型参数与知识底座调用链路对照

这一节是本文的核心产出：把 ReAct Agent 的模型参数和 WeKnora 知识底座的调用链路做成一张对照表。你可以直接把它当成接入检查清单。

层级	参数/动作	推荐值或说明
模型层	`base_url`	`https://taotoken.net/api`
模型层	`api_key`	`YOUR_API_KEY`，从 TaoToken 控制台创建
模型层	`model`	按任务选择，对话/推理/代码模型分开映射
模型层	`temperature`	ReAct 工具调用建议 0.1~0.3，降低乱调工具概率
模型层	`max_tokens`	单轮输出不要过大，避免挤占工具调用预算
模型层	`tool_choice`	需要强制检索时设为`auto`或指定函数
模型层	`parallel_tool_calls`	按供应商支持情况开启，建议先关后开
ReAct 层	`max_iterations`	3~8 轮起步，超过 10 轮要检查检索质量
ReAct 层	`search_top_k`	混合检索召回数，通常 10~30
ReAct 层	`rerank_top_n`	Rerank 后保留 3~8 条进入上下文
ReAct 层	`mcp_timeout`	按外部服务延迟设置，避免 Agent 卡死
ReAct 层	`sandbox_backend`	本地验证用 Docker，云端按需 E2B/Cube
知识底座	文档解析	PDF/Word/PPT/网页/飞书/Notion
知识底座	自适应分块	按标题、段落、表格结构切分
知识底座	混合检索	向量检索 + BM25，提升召回覆盖
知识底座	Rerank	对候选片段重排，控制上下文质量
知识底座	知识图谱	实体、概念、关系结构化
知识底座	Wiki Mode	Agent 自动整理 Markdown Wiki，可人工编辑回滚
知识底座	长期记忆	Profile、Preference、Fact、Task、Interest 等，需确认后写入

调用链路可以拆成 9 步：

用户在 WeKnora Web UI 或外部 Agent 发起问题。
WeKnora 对问题做改写或意图识别，生成检索查询。
混合检索同时走向量检索和 BM25，召回候选知识片段。
Rerank 模型对候选片段重排，保留最相关的若干条。
系统把问题、检索片段、工具定义组装成 ReAct 提示词。
ReAct Agent 通过 TaoToken 的 Base URL 调用模型，模型返回自然语言或tool_call。
如果返回tool_call，WeKnora 调用 MCP Server 或 Skill，必要时进入沙箱执行。
执行结果回填到对话上下文，模型进入下一轮推理。
达到停止条件后输出最终答案，并按规则写入长期记忆或 Wiki。

在这个链路里，TaoToken 的作用不是“再包一层”，而是把模型调用的 Key、Base URL、模型映射、Token 用量和错误处理统一起来。WeKnora 本身可以充当其他 Agent 的外部知识层，提供 API、CLI 和 MCP Server；不同 Harness 可以共享同一个知识层，但模型层完全可以是 TaoToken。这样你换模型供应商时，不需要改 WeKnora 的检索逻辑，也不需要动沙箱和 Skills。

4. Claude Code / Codex / CC Switch 三件套接入 TaoToken 的配置

很多 Agent 基础设施开发者不只跑 WeKnora，还会同时用 Claude Code、Codex、CC Switch 等工具。这里要严格区分：Claude Code 用ANTHROPIC_*环境变量，Codex 用config.toml，不要把ANTHROPIC_*套到 Codex 上。

4.1 Claude Code：settings.json 与 ANTHROPIC_*

Claude Code 的配置可以放在~/.claude/settings.json或项目级.claude/settings.json。把 Base URL 指向 TaoToken，Key 用YOUR_API_KEY：

{ "env": { "ANTHROPIC_BASE_URL": "https://taotoken.net/api", "ANTHROPIC_API_KEY": "YOUR_API_KEY", "ANTHROPIC_MODEL": "your-claude-model", "ANTHROPIC_SMALL_FAST_MODEL": "your-fast-model" } }

如果你使用 Claude Code 的插件或 MCP 能力，注意 MCP Server 的配置只负责让 Agent 访问 WeKnora 知识层，不要让 MCP 直接连生产数据库。需要查库时，让 Agent 调用一个受控的本地脚本或只读接口，SQL 由你在本地执行并脱敏。

4.2 Codex：config.toml 与自定义 model_provider

Codex 不使用ANTHROPIC_*。它的配置通常放在~/.codex/config.toml。下面是一个自定义供应商示例：

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

然后在 shell 里设置环境变量：

export TAOTOKEN_API_KEY=YOUR_API_KEY

验证配置：

codex --version codex "用一句话解释 WeKnora 的 ReAct 检索链路"

如果报 401，优先检查env_key对应的环境变量是否真的导出；如果报 404，检查base_url是否被重复拼接了/v1。

4.3 CC Switch 三件套：供应商、Key、模型映射

CC Switch 类工具的核心是三件套：供应商配置、API Key、模型映射。你可以按下面的结构组织，具体字段名以工具版本为准：

{ "name": "TaoToken", "base_url": "https://taotoken.net/api", "api_key": "YOUR_API_KEY", "models": { "default": "your-default-model", "fast": "your-fast-model", "reasoning": "your-reasoning-model", "coding": "your-coding-model" } }

三件套的好处是：WeKnora 里的 ReAct Agent 用reasoning或default，Claude Code 用coding，Codex 用fast或default，但底层都是同一个 TaoToken Key 和同一个 Base URL。这样既方便做 Token 用量隔离，也方便按任务切换模型。如果你需要更细的模型列表和对话测试，可以从模型对话入口进去试：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_chat 。

5. 排障：ReAct 多轮检索中的 401、429、tool_call 解析失败

WeKnora 的 ReAct Agent 一旦跑起来，最常见的问题不是“模型不会回答”，而是多轮工具调用中的工程错误。下面按错误类型拆。

5.1 401 Unauthorized

可能原因：

Key 没填或填错，占位符YOUR_API_KEY没替换。
Base URL 填成了https://taotoken.net/api/v1，客户端又自动补/v1。
环境变量没有传递到 Docker 容器内。

排查命令：

# 本地直接测试 TaoToken OpenAI 兼容接口 curl -sS https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "your-model-name", "messages": [{"role": "user", "content": "ping"}], "temperature": 0.1 }'

如果这条命令返回正常，说明 Key 和 Base URL 没问题，再去检查 WeKnora 容器内的环境变量。

5.2 429 Too Many Requests

ReAct 多轮检索会放大 Token 消耗：一次用户提问可能触发 3~8 次模型调用，每次还要带检索片段和工具定义。如果你同时跑多个 Agent，很容易撞到速率限制。处理方式：

降低max_iterations，先控制在 5 轮以内。
压缩检索上下文，Rerank 后只保留 3~5 条。
对高频问题做检索结果缓存。
把不同 Harness 的 Key 分开，便于观察用量。
需要更高配额时，考虑 Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_plan 。

5.3 tool_call 解析失败

典型表现：模型返回了自然语言，但没有按 schema 返回函数调用；或者返回了 JSON，但字段名不对。处理方式：

确认所选模型支持 function calling / tool use。
temperature调到 0.1~0.3。
工具定义用严格 JSON Schema，枚举值写全。
在 ReAct 提示词里明确“需要检索时必须调用 search_knowledge_base”。
如果模型不支持并行工具调用，关闭parallel_tool_calls。

5.4 沙箱执行超时

WeKnora 的 Skill Sandbox 支持 Docker、E2B、Cube。如果 Agent 在沙箱里跑 Python 处理 Excel 超时，先检查：

沙箱后端资源是否足够。
MCP 或 Skill 的超时时间是否太短。
是否在沙箱里访问了外部网络导致阻塞。

记住：沙箱是执行层，不是数据库连接层。不要让 Agent 在沙箱里直接连生产库，也不要把生产凭证写进 Skill。

6. 可复现实验：从文档入库到沙箱出报告的完整调用链

下面给出一条最小可复现路径，你可以按自己的环境调整。

步骤 1：创建 TaoToken Key进入控制台创建 Key，复制出来，后续统一用YOUR_API_KEY占位。链接：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_key2 。

步骤 2：配置 WeKnora 模型在 WeKnora 模型设置中选择 OpenAI 兼容供应商，Base URL 填https://taotoken.net/api，API Key 填YOUR_API_KEY，模型名填你在 TaoToken 侧确认可用的模型。保存后先做一次普通对话测试。

步骤 3：上传知识文档上传一份包含业务规则的 PDF，再上传一份 Excel。等待解析、分块、向量化完成。在检索测试里输入一个明确问题，确认能召回相关片段。

步骤 4：发起 ReAct 任务在对话里输入：“请根据知识库里的业务规则，分析我上传的 Excel，并生成一份 Markdown 报告。”观察 Agent 是否先调用知识检索，再调用沙箱 Skill 执行 Python。

步骤 5：查看调用链重点看日志里的模型调用次数、每次请求的 Token 数、tool_call 名称、沙箱执行结果。如果你用的是 TaoToken，可以按 Key 维度观察用量，方便判断是检索层太啰嗦，还是 ReAct 循环太多。

步骤 6：输出与回写最终报告返回后，检查是否满足要求。如果 WeKnora 开启了长期记忆或 Wiki Mode，确认哪些信息需要用户确认后写入，哪些只作为本次会话上下文。

这条链路跑通后，你得到的不只是一个问答机器人，而是一套可复用的 Agent 基础设施：WeKnora 管知识，ReAct Agent 管检索、MCP、Skills 和沙箱执行，TaoToken 管 Token 和模型接入。未来企业内部同时跑 Claude Code、Codex、自研 Agent 时，底层知识层可以共享，模型层可以按 Harness 分开配置。

7. 接入检查清单与下一步

在上线前，建议按下面清单过一遍：

[ ] WeKnora 已通过 Docker Compose 启动，http://localhost可访问。
[ ] 文档解析、混合检索、Rerank 链路已用最小数据集验证。
[ ] 模型 Base URL 为https://taotoken.net/api，Key 使用YOUR_API_KEY占位管理。
[ ] ReAct 的max_iterations、search_top_k、rerank_top_n已按业务调优。
[ ] Claude Code 使用ANTHROPIC_*，Codex 使用config.toml，没有混用。
[ ] CC Switch 三件套中供应商、Key、模型映射已分离。
[ ] MCP / Skill 没有直连生产库，SQL 和命令由本地受控执行。
[ ] 429 和 tool_call 解析失败有降级策略。
[ ] 长期记忆写入前有人工确认或规则校验。

如果你还没有开始接入，推荐按这个顺序走：先去模型对话页测试模型是否可用，再了解 Coding Plan 的配额是否适合你的 Agent 工作流，然后创建 API Key，最后按 Claude Code 文档把开发工具接上。模型对话入口：https://taotoken.net/models/detail/chat?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_chat2 ；Coding Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_plan2 ；创建 Key：https://taotoken.net/console/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_key3 ；Claude Code 文档：https://taotoken.net/doc/ClaudeCodeAnthropic?utm_source=taotoken_aicg_blog_end&utm_content=weknora_react_doc 。

WeKnora 把企业知识库从 RAG 推进到了 ReAct Agent、MCP、Skills、沙箱、Wiki 和 Memory 的组合，这是知识底座的一次升级。而 TaoToken 要解决的是另一侧的问题：当 Agent 开始多轮检索、多工具调用、多沙箱执行时，模型 Token 必须有统一的入口、清晰的 Base URL 和可观测的 Key 管理。底座管知识，网关管 Token，Agent 才能稳定地把“知道”变成“做到”。