简介：这是一份面向AI初学者的扣子（Coze）智能体快速部署源码包，帮助用户在没有编程基础的情况下，完成从智能体创建、角色设定、技能配置到插件扩展与多平台发布的完整流程。资源以陪伴机器人为示例，重点演示话题引导、情绪共鸣、创意互动等配置方法，并展示如何通过必应搜索插件扩展信息检索能力。包内包含3个文件，涵盖inscode可运行工程、HTML页面文件及gitignore配置文件，整体压缩包仅7KB，结构精简，便于零门槛上手并直接运行调试。目前已有239人学习使用，适合希望快速理解扣子平台核心操作、动手实践智能体部署的开发者。通过这份源码包，读者可对照代码理解每个配置环节的实现方式，并基于示例快速改造出属于自己的智能体，省去从零搭建环境的摸索时间。
1. 扣子智能体部署：3 分钟跑通云端，真正要落地的是本地运行时
扣子智能体部署这个标题，藏着两类完全不同的诉求：一类人刚注册完扣子控制台，想知道怎么把 Bot 跑起来、拿到可用的对话服务和源码；另一类人已经把手伸到生产环境，想把扣子智能体弄到自己服务器上，用本地模型接管对话，摆脱平台限制和按量计费。先给个反直觉结论：扣子智能体本身根本不用你部署，云端的 Bot 点一下发布就上线了，真正要部署的是你的运行时、你的调用层、你的模型底座。3 分钟能做的是跑通云端最小闭环，而想让一份可运行源码实实在在落在自己手里，后面还有 Docker、模型接入、工具编排这些硬骨头。这篇文章就把从「云端点几下」到「本地跑起来」的整条路拆开讲，每步都能直接抄。
2. 拆解扣子智能体：四层装配架构与「可运行源码」的三种含义
2.1 智能体不是一个程序，是四层组件的装配
扣子智能体从架构上看是一个典型的四层装配体，不理解这四层，后面看源码和部署文档会一头雾水。最上层是编排层，对应的是工作流画布和 Agent 节点，负责决定用户的问题进来之后先走哪个分支、调用哪个工具、哪一步该让大模型生成；第二层是运行时层，负责对话状态管理、记忆、多轮上下文维护和工具调用的调度逻辑；第三层是模型层，包括主对话用的大模型和做知识库检索用的 Embedding 模型；最底层是工具层，涵盖插件、知识库、API，以及现在讨论很多的 MCP 工具。
扣子官方的实现里，编排层是可视化 DAG，也就是把节点拖到画布上连线串起来。很多人问扣子是不是 LangGraph 实现的，其实不是，它只是和 LangGraph 在图执行思路上类似，内部完全是另一套实现。理解这一点对部署的意义在于：如果你想把扣子智能体迁移到本地开源方案，你要迁移的不是代码，而是「节点怎么编排、工具怎么接、模型怎么换」这套逻辑；如果你只想调用云端扣子，那你需要的源码只是调用侧的几十行代码，跟 Agent 内部实现毫无关系。
2.2 云端扣子怎么工作：从配置到运行时再到对外接口
在扣子控制台里创建的每个 Bot，本质上是一份非常结构化的配置。它包含人设与回复逻辑、模型选择与参数、知识库绑定关系、工作流 DAG 定义，以及工具列表。当你点击发布，扣子平台会把这堆配置实例化为一个运行中的智能体服务，对外暴露两类访问方式：一种是直接分享对话链接给终端用户，另一种是发布为 API，让开发者把 Bot 接进自己的产品里。
一份最简 Bot 配置，拆开看大致是下面这个样子，在扣子里导出时可以看到类似的 JSON 结构：
{ "bot_id": "7389xxxx", "model": { "provider": "doubao", "model_name": "doubao-pro-32k", "temperature": 0.3, "top_p": 0.7 }, "prompt": "你是一个负责处理售后问题的客服助手，回答要简洁、准确，不要编造订单信息。", "knowledge": [ { "datasets": ["售后政策", "退货流程"], "retrieval_mode": "mixed" } ], "tools": ["web_search", "order_query_api"] }这段配置的关键参数值得细说：model.provider决定走哪家模型服务商，在扣子云端你可以选豆包、DeepSeek、MiniMax 等；temperature控制在 0.3 左右适合客服这类要求稳定输出的场景，如果做创意文案再调高到 0.7 以上；retrieval_mode用mixed时知识库命中结果和生成结果会混合输出，回答更稳，但 token 消耗会明显上升。工具列表里的order_query_api不是扣子内置的，是你自己通过插件或工作流注册的外呼接口，这也就是后面「可运行源码」里真正需要自己写代码的部分。
2.3 「可运行源码」在扣子生态里到底指什么
从业者拿到标题里「可运行源码」这四个字时，必须先搞清楚它到底指哪份代码，因为不同阶段对应完全不同的东西。
第一种是扣子控制台里导出的 Bot 配置包。这个包不是传统意义的程序源码，它是描述智能体行为的 DSL 配置，可以在控制台之间迁移复用。第二种是调用侧源码，也就是你在自己的服务里写的 API 调用、消息接收、鉴权逻辑，这是绝大多数业务真正要维护的代码。第三种是开源扣子系智能体平台的源码，也就是社区里常说的开源扣子方案，这类平台部署到自己的服务器上，提供和扣子类似的编排画布和运行时能力，模型、知识库、工具全部由自己掌控。
想要拿到真正跑得起来的可运行源码，先走云端 API 调用是最快的路径，这也是下一章 3 分钟能完成的事情；等业务要求数据不出内网、模型要换成自己部署的 DeepSeek 时，再考虑拿一份开源扣子系方案做本地部署。
3. 用控制台 3 分钟搭出最小扣子 Bot：创建、发布与 Python 调用全流程
3.1 创建项目和选择模型：不是所有模型都适合当接待员
打开扣子控制台，新建一个项目，类型选「智能体」而不是「工作流」，因为智能体类型自带对话管理和模型调度能力。进入配置页后，第一步是选模型。扣子控制台默认会给你豆包系列模型，但如果你对输出格式有强要求，我一般会直接切到 DeepSeek 或者别的开源模型上，原因后面避坑章节会讲。
这里有几个参数第一次用就值得记下来。temperature是随机性控制，客服、问答类 Bot 设 0.2 到 0.4，代码生成类设 0.1，剧本写作类设 0.8 以上。max_tokens不建议设太高，控制在 1024 以内，否则一次回答会把上下文窗口吃掉一大半。reply_before_llm这类预回复规则只在你需要 Bot 先回复固定话术再进入模型生成时才开。
人设提示词的写法直接影响整个智能体的表现。最常见的问题是把所有要求糊成一大段，模型长上下文一长就漏掉关键约束。我通常把人设拆成「角色定位、行为边界、回答格式、禁忌项」四段，每段一两句话，禁忌项放最后，避免模型被前面的话带偏。
3.2 搭一个含知识库的极简工作流节点
扣子智能体的核心配置页里，除了人设，还要挂知识库。进入「知识库」页面，创建新的数据集，支持上传文本、表格、网页链接。上传之后要注意看分片状态，每个文档会被切成固定大小的片段并向量化，切片长度默认是 400 到 800 字，切片太短召回准但碎，太长召回全但混。如果你上传的是 Markdown 格式的说明文档，导出时保留标题结构非常重要，因为扣子的解析器会把标题作为这个切片的语义标签。
工作流画布里，第一根线通常是「开始 -> 模型 -> 结束」三个节点。模型节点里引用前面的人设参数，知识库通过「知识库检索」节点接进来。这里有一个新手必踩的坑：知识库检索节点一定要在模型节点之前执行，把检索结果拼进提示词，否则模型只能凭自己的训练记忆回答，知识库等于没挂。画完流程后点试运行，输入一句测试问题，看节点调试面板里检索结果和模型输出是否都正常。
3.3 发布到 API 并用 Python 跑通最小调用示例
控制台右上角「发布」，选择 API 服务方式。发布成功后，在 API 管理里能看到 Bot 的唯一标识bot_id，然后去个人访问令牌页面生成一个PAT（Personal Access Token）。这个令牌相当于你调用 API 的钥匙，权限范围选默认的应用权限即可，密钥一定要存好，泄露了随时可以在控制台吊销重新生成。
import requests import json BOT_ID = "7389xxxx" PAT = "pat_xxxx" body = { "bot_id": BOT_ID, "user_id": "tester_001", "stream": False, "auto_save_history": True, "additional_input": None } resp = requests.post( "https://api.coze.cn/v3/chat", headers={ "Authorization": f"Bearer {PAT}", "Content-Type": "application/json" }, json=body, timeout=30 ) result = resp.json() print(json.dumps(result, ensure_ascii=False, indent=2))这段代码是扣子 v3 联调的基本骨架。user_id是业务侧的用户标识，用来隔离每个用户的对话历史，同一个 user_id 的多轮消息会彼此衔接，这个参数在正式环境一定要传真实的用户 ID，不传或者传同一个固定值会导致所有用户串聊天记录。auto_save_history设为True时平台自动维护会话状态，省得自己管理历史消息，但如果你的业务对上下文有定制要求，可以关掉它自己传历史消息列表。
鉴权用的是Authorization: Bearer PAT，我见过很多人把扣子控制台里的别的密钥当成 PAT 用，返回 401 一脸懵。响应里的conversation_id和id两个字段要落库，前者是会话标识，后者是单次回复的消息 ID，后续做满意度评价、人工接管都靠这两个值。到这里，3 分钟跑通云端扣子智能体的最小闭环就成立了：控制台建 Bot、挂知识库、发布 API，再到拿到第一条响应。
4. 把可运行源码部署到自己的服务器：Docker Compose 拉起开源扣子系运行时并接入 DeepSeek
4.1 为什么本地部署智能体选「开源扣子系」而不是从零写
云端跑通之后，很多人会面临一个现实问题：扣子控制台的 Bot 玩得再熟，数据都在别人平台上，模型按 token 计费，知识库内容也受平台政策约束。这时候的唯一出路就是本地部署一套和扣子同思路的开源智能体运行时。业界常见做法是使用 Dify 这类开源智能体平台，社区里通常叫它「开源扣子系」，因为它们都提供可视化编排画布、知识库管理、模型接入和 API 发布能力。
这套方案的核心价值在于「可运行源码」可以真正落到自己手里。你需要一台 2 核 4G 以上的服务器，Docker 和 Docker Compose 先装好，然后从官方源码仓库拉一份部署文件，改配置、起容器、接入模型，半小时内能跑起来。相比从零用 LangChain 手搓一个 Agent，这套方案省掉了对话管理、会话持久化、知识库向量化这些重复造轮子的工作，而且模型层替换很容易，DeepSeek、Ollama、MiniMax 都能接。
4.2 最小可运行部署：docker-compose.yml 最小配置
部署文件是整个本地部署的核心，我把一份能直接启动的最简编排贴出来，服务裁剪到 API、数据库、向量存储三件套。注意版本号要根据你自己拉下来的源码指定，这里不写死具体版本。
version: "3.4" services: api: image: ${RUNTIME_IMAGE:-docker.io/langgenius/dify-api} restart: always environment: MODE: api EDITION: community DB_HOST: db DB_PORT: 5432 DB_DATABASE: dify DB_USERNAME: dify DB_PASSWORD: dify123 VECTOR_STORE: weaviate WEAVIATE_ENDPOINT: http://weaviate:8080 WEAVIATE_API_KEY: wv123 SECRET_KEY: your-random-secret-key depends_on: - db - weaviate ports: - "5001:5001" worker: image: ${RUNTIME_IMAGE:-docker.io/langgenius/dify-api} restart: always environment: MODE: worker EDITION: community DB_HOST: db DB_PORT: 5432 DB_DATABASE: dify DB_USERNAME: dify DB_PASSWORD: dify123 VECTOR_STORE: weaviate WEAVIATE_ENDPOINT: http://weaviate:8080 WEAVIATE_API_KEY: wv123 SECRET_KEY: your-random-secret-key depends_on: - db - weaviate db: image: postgres:15-alpine restart: always environment: POSTGRES_PASSWORD: dify123 POSTGRES_DB: dify POSTGRES_USER: dify volumes: - db_data:/var/lib/postgresql/data weaviate: image: semitechnologies/weaviate:1.19.0 restart: always environment: AUTHENTICATION_ANONYMOUS_ACCESS_ENABLED: "true" DEFAULT_VECTORIZER: none volumes: - weaviate_data:/var/lib/weaviate volumes: db_data: weaviate_data:这份文件把 API 服务和后台 Worker 分离，这是开源扣子系平台的标准做法。API 负责接收请求、做编排调度，Worker 负责异步跑知识库入库、文档分段、Embedding 生成这些耗时任务。VECTOR_STORE选 Weaviate 是因为社区版默认支持最省心，生产环境你可以换成 Qdrant 或者 pgvector，换的时候记得把对应的环境变量一起换掉，只改VECTOR_STORE一个值会导致启动报错。
启动命令就两行：
cp .env.example .env docker compose up -d启动之后不要急着进页面，先看日志：
docker compose logs -f api看到Application startup complete之类字样说明 API 起来了，然后访问服务器 IP 加对应端口，首次访问会引导你设置管理员账号。这个过程我踩过的坑是.env里SECRET_KEY不填随机字符串，直接用默认值，后面对接模型时加密密钥解析会莫名其妙报错。
4.3 把模型换成 DeepSeek 或 Ollama：开源扣子怎么添加模型的完整操作
部署完开源扣子系平台，下一步是添加模型。进管理后台的「模型供应商」配置页，常见做法是两种。
第一种接云端 DeepSeek。在供应商列表里选 DeepSeek，填Base URL为https://api.deepseek.com，填 API Key，模型名填deepseek-chat，这是 DeepSeek 官方对话模型的 API 模型标识，别想当然填deepseek-v3，接口不认。填完点「保存」然后先跑一次测试，平台会返回一条测试消息验证连通性。
第二种接本地 Ollama。如果你的服务器上已经用ollama pull deepseek-r1:7b拉好了模型，那么Base URL要填宿主机 IP，而不是localhost，因为开源扣子系平台跑在 Docker 容器里，容器内的 localhost 指向容器自己。我一般直接填http://172.17.0.1:11434，这是 Docker 默认网桥的宿主机入口，大多数情况下都通。模型名填你ollama list里看到的那个名字，比如deepseek-r1:7b。
除了对话主模型，还要配置 Embedding 模型。很多人在这一步跳过，结果知识库上传后提问时 Bot 回答「没有找到相关内容」。云端方案用text-embedding-ada-002或者开源系默认带的 embedding 模型都行；本地方案最常用的是bge-m3，同样通过 Ollama 加载，同一个供应商连接配置里选模型类型为embedding即可。
4.4 把云端扣子智能体迁到本地：知识库导入与工作流还原
本地平台跑起来之后，怎么把扣子上的智能体「搬」过来，这是最耗精力的环节。知识库相对简单：把扣子数据集里的源文件下载到本地，按 Markdown 或纯文本整理，在开源平台里重新建数据集上传，平台会自己完成分段和向量化。
工作流迁移则没有捷径，扣子导出的 DSL 是私有格式，主流开源平台有自己的一套 DSL，两者不能直接互导。我的做法是先在扣子那边把工作流截图成节点图，然后在开源平台里重新搭建相同结构的流程。扣子里常见做法是用「开始 -> 知识库检索 -> 模型 -> 结束」这种串联结构，平移到本地平台时把每个节点按同样的输入输出接起来，再用平台自带的调试功能对照扣子上的试运行结果逐步调整提示词变量。
扣子旧版工作流里的几个节点，比如快捷回复、意图识别，在开源平台的节点类型里不一定有直接对应项。处理办法是用模型节点加上结构化输出解析来模拟，也就是在提示词里让模型必须输出 JSON，再通过后续节点按字段路由。这块别想着自动化，人工逐一映射更稳妥，真实项目里 90% 的迁移工作量都花在这里。
工具层接 MCP 也不复杂——扣子链接 MCP 在云端是填服务地址，本地平台上一样。「工具」配置里新建 MCP 工具，填上streamable http或sse端点地址，平台会自动拉取工具描述，后续工作流节点里就能选用这些工具方法。有一点要注意：MCP 服务端的地址要保证容器网络能访问到，部署在同一台服务器就用宿主机 IP，不要用localhost。
5. 扣子系智能体部署避坑：五个真实翻车现场的原因与修复
5.1 API 返回 401/403，密钥明明没问题
现象：按官方文档填了Authorization头，调用扣子 v3 接口一直返回 401，检查若干遍感觉密钥没问题。
原因：八成是把平台里不同类型的令牌搞混了。扣子控制台里「API 密钥」页面生成的是 PAT，而一些旧教程里让填的是个人访问令牌页面里另一个入口生成的临时 Token，两者权限范围和解码方式不同。另外 PAT 有有效期，过期后接口同样报 401。
解决：统一去「个人访问令牌」页面重新生成 PAT，直接覆盖原密钥；生成时权限范围勾选你实际要调用的平台能力，不要图省事全选。程序里把 PAT 放到环境变量里，不要硬编码进仓库，否则一旦推送线上就等同公开，只能重新生成。
5.2 模型输出答非所问，人设提示词像没生效
现象：扣子控制台调试时 Bot 回答正常，发布到 API 后同样的输入得到的回答偏离人设，甚至开始胡说八道。
原因：控制台调试环境和 API 服务的上下文处理不一样。发布后如果additional_input传入了额外字段，这些字段会拼到系统上下文里干扰 prompt；另外temperature设置过高会让模型在长上下文中跑偏。
解决：把temperature固定到 0.2 到 0.4 区间；人设提示词里把最关键的约束放到第一句，让模型在任何上下文拼接下优先读到它。逐字检查additional_input里的键名，别和系统字段重名，平台文档里明令保留的字段名一个都不要用。
5.3 工作流中 HTTP 节点反复失败，时好时坏
现象：扣子工作流里接了自己业务系统的查询接口，调试时 60% 概率失败，错误信息是超时，偶尔成功。
原因：扣子云端执行工作流时，HTTP 节点的默认超时时间很短，跨网访问你的业务接口，只要对方响应超过几秒钟就断。另一个常见原因是接口返回了非标准 JSON，扣子节点解析失败直接当错误处理。
解决：给业务接口做一层薄封装，固定返回{"code":0,"data":{...}}这样的小写字段结构；在 HTTP 节点里把超时参数调到允许范围内的最大值，并添加失败分支节点，超时后返回兜底话术而不是让整个对话报错。
5.4 本地部署后 Bot 变成失忆症：知识库明明导入了
现象：开源扣子系平台本地部署完后，模型能正常聊天，但一问到知识库里的专属内容就回答不知道；去向量数据库看，文档确实入库了。
原因：典型的两处配置错误。一是只配置了对话模型，没有配置 Embedding 模型，系统用默认的空实现，入库时向量全是零向量，检索自然什么都召不回；二是知识库文档分段参数不合理，整篇大文档没分段就入库，导致每个片段都是几千字的大杂烩，检索召回后模型读不懂。
解决：在模型供应商里把 Embedding 模型补齐，重新建数据集，强制重新分段和向量化。分段长度我一般设在 500 字左右，重叠 50 字，这样既保留上下文连贯性又提高召回精度。改完后在知识库页面做一次「召回测试」，输入一句典型业务问题，看返回的片段是否和自己预期一致。
5.5 Docker 部署后内存爆满，服务器直接卡死
现象：Docker Compose 拉起来镜像后跑了半天，服务器负载飙升，free -m看内存几乎耗尽，数据库容器被系统 OOM 杀掉。
原因：docker-compose.yml没有给每个容器设置内存上限，而开源扣子系平台默认会预加载模型，多个容器同时吃内存；再加上对话并发高时 Worker 里同时跑多个 Embedding 任务，内存就像漏斗一样漏下去。
解决：在docker-compose.yml的 api、worker、weaviate 服务下都加上deploy.resources.limits配置，比如 API 限 1GB、数据库限 1GB、向量库限 1GB；同时调低 Worker 并发数，限制 Embedding 任务的并行度，别让一堆入库任务同时在内存里做矩阵运算。
6. 上线前的最后一步：给智能体写一份可回归的验收脚本
部署完成不等于交付，真正让人放心的是每次改完 prompt、换完模型、调完参数后，能有一份脚本替你把关键场景全部回归一遍。这套东西在团队协作里非常重要：开发说「我就改了个提示词」，测试说「这轮明显变蠢了」，没有回归脚本就只能靠肉眼一轮轮聊。
我通常会给每个智能体维护一个cases.json，里面是典型场景的输入、期望行为关键词、允许的最大响应时间。回归脚本也很简单：
import requests import json import time cases = json.load(open("cases.json")) for idx, case in enumerate(cases, 1): start = time.time() resp = requests.post( "http://localhost:5001/chat-messages", headers={"Authorization": f"Bearer {API_KEY}"}, json={ "inputs": {}, "query": case["query"], "user": "regression_test", "response_mode": "blocking", }, timeout=60, ) elapsed = time.time() - start answer = resp.json().get("answer", "") status = "PASS" if resp.status_code != 200: status = "FAIL_HTTP" elif elapsed > case["max_time"]: status = "FAIL_TIMEOUT" elif not any(kw in answer for kw in case["expected_keywords"]): status = "FAIL_CONTENT" print(f"case {idx}: {status}, {elapsed:.1f}s, {case['query']}")这段脚本的作用不是自动化测试框架那么重，而是当你在扣子和本地开源平台之间来回调参时的后悔药。每次改完人设，先生成一批新旧对照跑一遍，别靠手感判断好坏。等稳定了，再把它接进 CI，每天跑一次，模型供应商如果偷偷换了底层模型版本，第一时间就能在输出质量变化上观察到。
我自己的习惯是验收脚本里固定跑 20 到 30 个真实业务问题，覆盖售前、售后、闲聊、对抗输入四类，其中对抗输入至少占 5 条，专门测越狱和诱导。最初部署第一个扣子智能体时，我把全部精力都放在提示词上，上线第一天就被并发把服务打崩了，后来才意识到部署一件事要看的从来不只是模型输出质量，还有超时、限流、资源占用这些更底层的指标。希望这篇能帮你把扣子智能体部署这条路走顺，少交几次学费。
本文还有配套的精品资源，点击获取
