1. 从 WeKnora 的 ReAct 配置切入模型出口为什么要单独抽出来在 WeKnora 里跑通一次 ReAct 问答真正让人卡住的往往不是文档解析而是模型出口分散在多个配置面WeKnora 的 LLM 环境变量、Claude Code 的ANTHROPIC_*、Codex 的config.toml、CC Switch 的供应商档案。只要其中一处 Base URL 写错Agent 就会在“调用知识库”和“调用模型”之间来回失败。我现在的做法是把模型推理出口统一到 TaoTokenBase URL 固定为https://taotoken.net/apiKey 从 TaoToken 官网 创建。这样 WeKnora 的 ReAct Agent、MCP Client、Skill Sandbox以及外面的 Coding Agent都走同一套模型凭证排查时只看一条链路。WeKnora 的定位不是“和 PDF 聊天”。它把文档解析、自适应分块、向量检索、BM25 混合搜索、Rerank、知识图谱、长期记忆、Wiki Mode、Skill Sandbox 串起来再把 ReAct Agent 放在上面做多轮工具调用。对 Agent 开发者来说这意味着一次问答里至少有两类调用一类是模型推理调用另一类是知识库/工具调用。前者决定 ReAct 的规划质量后者决定 Observation 是否可信。本文不讨论新闻层面只给一套可复现的接入方式模型参数、Token 流向、Claude Code / Codex / CC Switch 配置以及常见报错怎么排查。先看整体链路用户问题 - WeKnora Web/API/CLI - ReAct Agent模型TaoToken Base URL - Thought / Action - 知识库检索向量 BM25 Rerank - MCP 工具调用 - Skill SandboxDocker/E2B/Cube - Observation 回填 - 多轮循环直到 Final Answer - 返回答案 引用 生成文件这里模型只负责“想”和“决定调什么”知识库和沙箱负责“查”和“做”。把模型出口换成 TaoToken 后模型参数、Token 消耗、错误码都集中在一个 Base URL 下方便做团队规范。2. 准备 WeKnora 与 TaoTokenKey、Base URL、模型名三件套第一步不是改代码而是准备三件套Base URL、API Key、模型名。Base URL 用https://taotoken.net/api不要在后面随手加/v1或斜杠。API Key 去 TaoToken 官网控制台 创建占位符统一写成YOUR_API_KEY不要提交到 Git。模型名以 TaoToken 控制台当前可用列表为准选支持工具调用/函数调用的模型ReAct 链路会更稳。WeKnora 推荐 Docker Compose 启动。你可以先在本地把服务跑起来再在 Web UI 里配置模型。不同版本的变量名可能略有差异下面给的是常见写法具体以你拉取的那一版docker-compose.yml和.env.example为准# .env 示例WeKnora 侧模型出口 LLM_PROVIDERopenai_compatible LLM_BASE_URLhttps://taotoken.net/api LLM_API_KEYYOUR_API_KEY LLM_MODELYOUR_TOOL_CALL_MODEL LLM_TEMPERATURE0.3 LLM_MAX_TOKENS4096 # 如果 WeKnora 使用 OpenAI 兼容客户端通常还会读取下面这类变量 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_API_KEYYOUR_API_KEY # 检索与 Rerank 相关参数 RETRIEVAL_TOP_K8 RERANK_TOP_K4 HYBRID_SEARCH_ENABLEDtrue启动后访问本机 Web UI先导一份小文档验证检索再打开 ReAct Agent。不要一上来就把生产文档全量灌进去先用测试知识库确认模型能正常返回工具调用。如果你的 WeKnora 版本把模型配置放在config.yaml写法类似llm: provider: openai_compatible base_url: https://taotoken.net/api api_key: YOUR_API_KEY model: YOUR_TOOL_CALL_MODEL temperature: 0.3 max_tokens: 4096 timeout: 60这里的关键点WeKnora 只认一个模型出口TaoToken 的 Base URL 同时服务 ReAct 规划、工具调用参数生成、最终答案生成。不要把同一个 Key 写进多个容器环境也不要在前端明文保存。3. ReAct 问答链路的模型参数稳定 Tool Call 的配置模板ReAct Agent 对模型参数比普通聊天敏感。温度太高Action 名称和参数容易漂温度太低遇到需要归纳的场景又可能过于死板。我一般用下面这组起点再按模型特性微调。参数建议值作用调参方向temperature0.2 - 0.4控制规划随机性工具调用不稳定就降到 0.1 - 0.2top_p0.8 - 0.95核采样与 temperature 二选一重点调max_tokens4096 - 8192单轮输出上限工具参数长就调大但会增加延迟tool_choiceauto是否强制调用工具需要固定入口时可临时用 requiredparallel_tool_callsfalse是否并行调用ReAct 多轮依赖 Observation 时建议关max_iterations6 - 10ReAct 循环上限防止死循环复杂任务可到 12timeout60 - 120s模型请求超时沙箱任务长可调大retry2网络失败重试只重试幂等请求对应到 WeKnora 的 ReAct 配置可以抽象成这样{ react: { max_iterations: 8, early_stop: true, tool_choice: auto, parallel_tool_calls: false, observation_max_chars: 6000 }, llm: { base_url: https://taotoken.net/api, api_key: YOUR_API_KEY, model: YOUR_TOOL_CALL_MODEL, temperature: 0.3, top_p: 0.9, max_tokens: 4096, timeout: 90 }, retrieval: { top_k: 8, rerank_top_k: 4, hybrid: { vector_weight: 0.6, bm25_weight: 0.4 } } }为什么要限制observation_max_chars因为知识库返回的 Chunk 和沙箱输出会原样进入下一轮上下文。如果一次塞几万字符Token 消耗会快速上升ReAct 还可能被无关内容带偏。把 Observation 截断到 6000 字符左右再让 Rerank 提前过滤通常更稳。模型侧每轮都会消耗输入 Token多轮 ReAct 的实际成本是“轮数 × 上下文长度”所以参数不是孤立的要和检索 TopK 一起看。4. Token 流向说明图从用户问题到 WeKnora 沙箱再回到模型下面这张图建议直接贴到你的项目 README 或排障手册里。它把“模型调用”和“知识/工具调用”拆开出问题时可以按节点定位。┌──────────────────────────────────────────────────────────────┐ │ 1. 用户问题 │ │ 根据知识库里的报销规则分析这份 Excel 并生成 CSV │ └──────────────────────────────┬───────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────┐ │ 2. WeKnora ReAct Agent │ │ - 组装 system prompt 历史消息 工具清单 │ │ - 向 https://taotoken.net/api 发起模型请求 │ │ - Key: YOUR_API_KEY │ └──────────────────────────────┬───────────────────────────────┘ │ 模型返回 Thought / Action v ┌──────────────────────────────────────────────────────────────┐ │ 3. 工具路由层 │ │ ├─ 知识库检索向量 BM25 - Rerank - TopK Chunk │ │ ├─ MCP 工具业务系统只读接口、查询工具本地/测试环境 │ │ └─ Skill SandboxDocker / E2B / Cube 执行 Python、Shell │ └──────────────────────────────┬───────────────────────────────┘ │ Observation v ┌──────────────────────────────────────────────────────────────┐ │ 4. 回填模型 │ │ - Observation 原问题再次发送到 TaoToken │ │ - 重复 2-4直到 Final Answer 或达到 max_iterations │ └──────────────────────────────┬───────────────────────────────┘ │ v ┌──────────────────────────────────────────────────────────────┐ │ 5. 输出 │ │ - 答案 引用文档 生成文件CSV/报告 │ │ - 记录每轮 model、token 用量、工具耗时 │ └──────────────────────────────────────────────────────────────┘Token 消耗主要发生在第 2 和第 4 步。第 3 步的检索本身不消耗模型 Token但检索结果会变成第 4 步的输入。Skill Sandbox 执行代码也不消耗模型 Token除非你把执行日志再交给模型总结。因此优化方向有三个减少无效检索、压缩 Observation、控制 ReAct 轮数。对于企业知识库场景Rerank 之后只保留 3-5 个高相关 Chunk通常比把所有搜索结果丢给模型更省。5. 把 Claude Code、Codex、CC Switch 接到同一套 WeKnora 知识层WeKnora 提供 API、CLI 和 MCP Server可以作为其他 Agent 的外部知识层。团队已经为 DeepSeek Harness 提供官方插件wxg-prc-cpg/dsh-weknora接入后 Coding Agent 可以搜索知识库、读取完整文档或调用 RAG / ReAct 流程。下面把常见三个入口的配置拆开写。注意Claude Code 用ANTHROPIC_*Codex 用config.toml不要混用。5.1 Claude Codesettings.json 与 ANTHROPIC_*Claude Code 侧继续使用 Anthropic 兼容变量Base URL 指向 TaoTokenKey 用YOUR_API_KEY{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: YOUR_API_KEY, ANTHROPIC_MODEL: YOUR_CLAUDE_MODEL, ANTHROPIC_SMALL_FAST_MODEL: YOUR_FAST_MODEL } }如果你通过 shell 临时验证可以这样导出再启动 Claude Codeexport ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENYOUR_API_KEY export ANTHROPIC_MODELYOUR_CLAUDE_MODEL验证时先让它读一个本地文件再让它通过 WeKnora MCP 查一条知识库记录。如果本地文件能读、知识库查询失败问题通常在 MCP Server 配置不在模型出口。5.2 Codexconfig.toml 单独配置Codex 不要用ANTHROPIC_*它读取~/.codex/config.toml。示例model_provider taotoken model YOUR_CODEX_MODEL model_reasoning_effort medium [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY wire_api responses然后在 shell 里设置export TAOTOKEN_API_KEYYOUR_API_KEY如果你使用的是 Chat Completions 兼容模式把wire_api按 Codex 版本文档调整。原则只有一个Base URL 保持https://taotoken.net/apiKey 从环境变量读不写进config.toml明文。5.3 CC Switch供应商、模型、配置目录三件套CC Switch 用来在多个供应商和多个 Agent 之间切换。把它理解成三件套供应商档案、模型档案、配置落盘目录。新增 TaoToken 供应商时填字段值名称TaoTokenBase URLhttps://taotoken.net/apiAPI KeyYOUR_API_KEY默认模型YOUR_TOOL_CALL_MODEL适用客户端Claude Code / Codex / 自定义 OpenAI 兼容客户端一个简化的 CC Switch 配置片段可以写成{ providers: [ { name: taotoken, base_url: https://taotoken.net/api, api_key_env: TAOTOKEN_API_KEY, models: { claude_code: YOUR_CLAUDE_MODEL, codex: YOUR_CODEX_MODEL, weknora_react: YOUR_TOOL_CALL_MODEL } } ], active: taotoken }切换后分别检查 Claude Code 的ANTHROPIC_BASE_URL、Codex 的base_url、WeKnora 的LLM_BASE_URL是否都指向同一个 TaoToken 出口。很多“知识库检索正常但 Agent 不回答”的问题最后都是某个客户端还在用旧供应商。6. 常见报错与排障401、404、ReAct 死循环、沙箱失败排障按“模型出口 - 工具路由 - 检索质量 - 沙箱”顺序查不要一上来就调 Prompt。现象可能原因处理401 / invalid api keyKey 写错、环境变量未加载、复制了空格重新从控制台创建 Key检查YOUR_API_KEY替换是否完整404 / model not foundBase URL 多了/v1、模型名不存在统一 Base URL 为https://taotoken.net/api模型名从控制台复制403 / permission deniedKey 权限或模型未开通在控制台确认模型权限与配额ReAct 死循环工具反复返回空、Observation 太长降低max_iterations设置 early stop压缩 Observation工具调用参数为空模型工具调用能力弱或 temperature 高换支持 function call 的模型temperature 降到 0.2知识库检索为空分块、混合检索权重、Rerank 阈值先只用向量检索验证再打开 BM25再调 Rerank沙箱执行失败Docker 权限、E2B/Cube 凭证、工作区只读检查后端配置与会话工作区权限长期记忆不召回记忆未确认写入、召回条件不匹配确认用户确认流程检查 Profile/Preference/Fact 类型一个本地连通性测试可以这样写命令由你在本地执行curl -sS https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: YOUR_TOOL_CALL_MODEL, messages: [ {role: user, content: 只回复 pong} ], temperature: 0 }如果这条命令失败先不要动 WeKnora如果它成功但 WeKnora 失败就去看 WeKnora 容器内的环境变量是否注入到了正确的进程。Docker Compose 场景下改完.env要重新docker compose up -d只重启一个服务可能读不到新变量。7. 可复现实验上传 Excel走完一次 ReAct Skill Sandbox下面用一个可复现的小任务串起链路企业知识库里放一份“差旅报销规则”Markdown上传一份测试 Excel问 Agent“根据知识库中的报销规则计算这份 Excel 里每个人的可报销金额并生成 CSV。” 这个任务会同时触发知识库检索和 Skill Sandbox。操作步骤启动 WeKnora在 Web UI 或 API 中创建测试知识库。导入差旅报销规则.md等待解析、分块、向量化完成。配置模型出口Base URL 为https://taotoken.net/apiKey 为YOUR_API_KEY模型选支持工具调用的模型。打开 ReAct Agent设置max_iterations8temperature0.3。上传测试报销.xlsx输入上面的问题。查看 Trace应该出现“检索知识库 - 找到规则 - 调用沙箱执行 Python - 生成 CSV - 返回文件”。一次典型的 ReAct Trace 可以抽象成[Round 1] Thought: 需要先找到公司的差旅报销规则。 Action: knowledge_search(query差旅报销规则 餐补 住宿标准) Observation: 命中 3 个 ChunkRerank 后保留 2 个。 [Round 2] Thought: 规则已找到需要读取 Excel 并计算。 Action: skill_sandbox(execpython analyze_expense.py /workspace/测试报销.xlsx) Observation: 生成 /workspace/result.csv共 12 行。 [Round 3] Thought: 已得到结果可以总结并返回文件。 Action: final_answer Observation: 返回 CSV 下载链接与计算说明。这个实验里模型调用了两次以上每次输入都包含系统提示、历史、工具结果。Token 流向如下阶段模型调用输入主要内容输出主要内容Round 1是问题 工具清单检索 ActionRound 1 后否知识库检索Chunk 引用Round 2是问题 规则 Excel 信息沙箱 ActionRound 2 后否沙箱执行CSV 结果Round 3是历史 CSV 摘要Final Answer把每轮的usage.prompt_tokens、usage.completion_tokens、工具耗时记下来就能知道成本花在检索回填还是最终总结。通常 ReAct 轮数越多输入 Token 增长越快所以max_iterations和observation_max_chars是两个必须显式设置的参数。8. 团队落地建议把 Key、Base URL、模型参数做成 Profile单机跑通只是第一步。团队里通常同时存在 WeKnora、Claude Code、Codex、DeepSeek Harness 和自研 Agent如果每个工具都单独填 Key最后会出现“同一个模型出口五份不同配置”。建议用 CC Switch 或内部配置中心做 Profile至少分环境profiles/ dev.env staging.env prod.env 每个 profile 包含 - TAOTOKEN_BASE_URLhttps://taotoken.net/api - TAOTOKEN_API_KEY从密钥管理注入 - WEKNORA_LLM_MODELYOUR_TOOL_CALL_MODEL - CLAUDE_MODELYOUR_CLAUDE_MODEL - CODEX_MODELYOUR_CODEX_MODEL安全上Key 只放环境变量或密钥管理器不写进镜像、不提交 Git。审计上记录每次模型调用的模型名、轮数、Token 用量和工具名但不记录完整知识库内容。WeKnora 的长期记忆写入前要用户确认这个机制在团队场景里尤其重要避免把临时对话当成企业事实。官网入口放在这里方便统一获取 Key 与查看模型列表TaoToken 官网。Base URL 不需要 UTM配置里始终写https://taotoken.net/api。9. 下一步从一次问答到一套可审计的 ReAct 链路如果你已经跑通上面的 Excel 实验下一步可以做三件事第一把知识库检索、MCP 调用、Skill Sandbox 的 Trace 统一收集定位每轮 Token 花在哪里第二把模型参数按任务类型分成“检索型”“代码型”“总结型”在 CC Switch 里建多个模型档案第三把 WeKnora 作为共享知识层让 Claude Code、Codex 和自研 Agent 只通过 MCP/API 访问不把数据库凭证直接交给 Agent。SQL 和系统命令由读者在本地或测试环境执行不要让 Agent 直连生产库。文末 CTA 按这个顺序走先到 模型对话 验证模型与工具调用参数。需要长期跑 Coding Agent看 Coding Plan。到 API Keys 创建YOUR_API_KEY。Claude Code 用户继续看 Claude Code 文档把settings.json里的ANTHROPIC_BASE_URL指向https://taotoken.net/api。把 WeKnora 的 ReAct Agent 接上 TaoToken 后知识库、MCP、Skills 和沙箱仍然是 WeKnora 在管模型出口则收敛成一个 Base URL 和一个 Key。这样无论上层是 Claude Code、Codex 还是自研 AgentToken 从哪出、请求发到哪、每一轮花在什么地方都能对得上。