1. 为什么要在 Chatbox 里接 LangGraph 智能体Chatbox 是一款跨平台的 AI 客户端支持 Windows、macOS、Linux走的是 OpenAI 兼容的 API 调用方式。它本身能连 OpenAI、Claude、DeepSeek 这类云端模型也能连本地 vLLM、Ollama 部署的模型。对很多本地 AI 工具链搭建者来说Chatbox 就是日常和大模型对话的入口。但问题在于你用 LangGraph 写好的智能体默认并不是一个「模型后端」。LangGraph 的产物是一个可执行图它接收消息、调用工具、返回结果但它不会自动暴露成 OpenAI 风格的/chat/completions接口。于是你面临一个尴尬智能体写完了却只能靠脚本或 agent-chat-ui 去调想用 Chatbox 这种顺手的客户端直接聊就得自己搭一层适配。我试过最省事的做法是用 FastAPI 把 LangGraph 智能体包一层 OpenAI 兼容接口再让 Chatbox 把它当成一个「模型提供方」来连。这样 Chatbox 不需要知道背后是 LangGraph它只认 OpenAI 格式。而在这条链路里TaoToken 负责统一 Key 和 API 通道Trae Solo 负责把适配层代码快速生成并本地跑起来。三者配合就能让 Chatbox 稳定调用 LangGraph 智能体。这篇面向的是本地 AI 工具链搭建者你已经有 LangGraph 智能体代码想用 Chatbox 当入口同时希望 Key 管理不散落在各个文件里。下面从 TaoToken 前置准备开始给出可复制的settings.json与config.toml骨架、Key 写入位置以及 Trae Solo 侧的联调验证动作。2. TaoToken 前置统一 Key 与 API 通道在动手写适配层之前先把 Key 和通道理顺。很多人的痛点是LangGraph 智能体里写死了 DeepSeek 的 keyChatbox 里又配了一份Trae Solo 生成的代码里可能还有第三份。一旦要换模型或换通道就得满项目找 key。TaoToken 在这里的角色是统一入口。你可以在官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台创建 API Key。这个 Key 就是你后续所有调用统一使用的凭证。API 基地址是 https://taotoken.net/api注意这个地址不带 UTM 参数直接用于代码里的base_url。具体操作路径登录后进入控制台找到 API Keys 页面新建一个 Key 并复制保存。这个 Key 会同时用在两个地方——LangGraph 智能体初始化模型时以及 Chatbox 配置模型提供方时。这样你只需要维护一份 Key换通道时改一处即可。注意Key 不要硬编码进提交到 Git 的代码里。建议用环境变量或本地配置文件承载下面给出的config.toml和settings.json骨架就是为此设计的。如果你还想先验证模型通道是否通可以打开模型对话页面直接发一条消息测试。确认通道可用后再进入编码环节。对于长期做编码和 Agent 开发的场景Coding Plan 页面也值得看一眼它更适合高频调用。3. 可复制配置settings.json 与 config.toml 骨架这一节给出两个骨架文件。config.toml用于 LangGraph 智能体侧读取模型配置settings.json用于 Chatbox 侧配置模型提供方。两者都指向 TaoToken 的统一通道。先看config.toml放在项目根目录# config.toml [llm] base_url https://taotoken.net/api api_key sk-你的TaoTokenKey model deepseek-chat temperature 0.7 [agent] system_prompt 你是一名可爱的天气预报播报员可以模仿林志玲的语气播报天气具备调用get_weather天气函数获取指定地点天气的能力LangGraph 智能体初始化模型时从这份配置读取import tomli from langchain.chat_models import init_chat_model with open(config.toml, rb) as f: cfg tomli.load(f) model init_chat_model( modelcfg[llm][model], base_urlcfg[llm][base_url], api_keycfg[llm][api_key], temperaturecfg[llm][temperature], )再看 Chatbox 侧的settings.json骨架。Chatbox 的模型提供方配置本质上是 OpenAI 兼容格式关键字段是apiHost和apiPath{ providers: [ { id: langgraph-weather, name: LangGraph 天气助手, type: openai, apiHost: http://localhost:8001, apiPath: /chat/completions, apiKey: sk-你的TaoTokenKey, models: [ { id: deepseek-chat, name: 天气助手, maxTokens: 2048, temperature: 0.7 } ] } ] }这里有个容易踩的坑apiHost填的是你本地 FastAPI 服务的地址不是 TaoToken 的地址。因为 Chatbox 连的是你的适配层适配层再去连 TaoToken。apiKey填 TaoToken 的 Key是为了让适配层在转发时能带上统一凭证。如果你把apiHost直接填成 TaoToken 地址那就绕过了 LangGraph 智能体变成直接调模型了。适配层的 FastAPI 代码骨架核心是把 OpenAI 请求转成 LangGraph 的invoke调用再把结果封装回 OpenAI 响应。流式部分用StreamingResponse逐字返回from fastapi import FastAPI from fastapi.responses import StreamingResponse from pydantic import BaseModel from typing import List, Optional import json, time from langchain_weather import agent app FastAPI(titleLangGraph Weather API) class Message(BaseModel): role: str content: str class ChatRequest(BaseModel): model: str deepseek-chat messages: List[Message] stream: Optional[bool] False app.post(/chat/completions) async def chat_completions(req: ChatRequest): user_msg req.messages[-1].content result agent.invoke({messages: [{role: user, content: user_msg}]}) content result[messages][-1].content if req.stream: def gen(): for ch in content: chunk {choices: [{delta: {content: ch}, index: 0}]} yield fdata: {json.dumps(chunk, ensure_asciiFalse)}\n\n time.sleep(0.05) yield data: [DONE]\n\n return StreamingResponse(gen(), media_typetext/event-stream) return { id: chatcmpl-local, object: chat.completion, choices: [{index: 0, message: {role: assistant, content: content}, finish_reason: stop}], }启动命令用 uvicorn端口选 8001避免和常见服务冲突uvicorn main:app --host 0.0.0.0 --port 80014. Trae Solo 联调验证从生成到跑通Trae Solo 的价值在于你不需要手写上面那堆适配代码。在 Trae 里切到 SOLO 模式用自然语言描述需求即可。我用的提示词是这样的你是一名 Python 编程专家熟练掌握 LangChain 1.0 开发智能体、FastAPI 编写接口的能力。项目中的langchain_weather.py包含一个天气助手智能体请用 FastAPI 编写 OpenAI 风格的流式接口使该智能体可被 Chatbox 等客户端以 API 格式接入并本地启动接口。Trae Solo 接到需求后会自主执行一串动作先分析langchain_weather.py识别出未定义类型之类的 bug然后新建main.py写接口测试时发现导入问题会自动修复启动时用 uv 创建虚拟环境检测到端口占用会循环换端口最后用 curl 和测试脚本验证服务稳定性。联调验证分三步。第一步确认 FastAPI 服务起来了curl -X POST http://localhost:8001/chat/completions \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:北京天气}],stream:false}如果返回里包含天气信息和播报语气说明适配层通了。第二步在 Chatbox 里按第 3 节的settings.json配置模型提供方API 主机填http://localhost:8001API 路径填/chat/completions。第三步在 Chatbox 对话框输入「上海的天气」观察是否流式返回。实测下来只要config.toml里的 TaoToken Key 正确、base_url指向https://taotoken.net/api整条链路就能跑通。Chatbox 看到的是一个 OpenAI 兼容后端LangGraph 智能体在背后完成工具调用和结果生成。5. 本篇常见错排查第一个高频错误是 401。表现是 Chatbox 发消息后返回鉴权失败。原因通常是config.toml里的api_key没填对或者 Chatbox 的apiKey字段留空。排查方法先用 curl 直接打本地 8001 端口如果 curl 也 401说明是适配层读 Key 的问题如果 curl 正常但 Chatbox 401说明是 Chatbox 配置里的 Key 没填。第二个错误是 404。表现是 Chatbox 提示找不到接口。原因多半是apiPath写错。Chatbox 的apiHost和apiPath是拼接关系最终请求地址是http://localhost:8001/chat/completions。如果你在apiHost里已经带了/chat/completions又在apiPath里重复写就会变成双路径导致 404。第三个错误是流式输出卡住或一次性吐出。原因是适配层里stream参数没正确判断或者StreamingResponse的 media type 写成了application/json。正确写法是text/event-stream并且每个 chunk 要以data:开头、以\n\n结尾。第四个错误是端口占用。Trae Solo 生成的服务默认可能用 8000而 8000 常被其他服务占用。解决办法是在启动命令里显式指定 8001或者让 Trae Solo 自动处理端口冲突。如果你手动启动记得检查uvicorn.run里的 port 参数。第五个错误是 LangGraph 智能体返回结构解析失败。不同版本的 LangGraph 返回可能是 dict 也可能是 Message 对象。适配层里要兼容两种情况先判断isinstance(result, dict)再取result[messages][-1]否则直接取result.content。这个坑在 Trae Solo 生成的代码里通常已经处理但如果你手改过要留意。6. 把 Key 和通道固定下来整条链路跑通后建议把 TaoToken 的 Key 固定到环境变量里而不是留在config.toml明文。比如在 shell 里 export 一个TAOTOKEN_API_KEY然后config.toml里用占位符代码读取时从环境变量取。这样换机器或换 Key 时只改一处。Chatbox 侧的配置也一样settings.json里的apiKey可以留空改由适配层统一注入。因为 Chatbox 连的是你本地服务本地服务再去连 TaoTokenKey 只需要在适配层维护一份。这样你的 Chatbox 配置可以分享给别人而 Key 不会泄露。如果你后续要接更多 LangGraph 智能体比如多模态 RAG 或者带记忆的对话图思路是一样的每个智能体包一个 FastAPI 适配层监听不同端口Chatbox 里加多个模型提供方即可。TaoToken 的 Key 和通道保持不变新增的只是适配层。需要创建 Key 或查看通道状态可以走 API Keys 页面接入细节和参数说明看接入文档想先验证模型通道是否正常用模型对话页面发一条消息最快。长期做编码和 Agent 开发的话Coding Plan 会更省心。
