部署 AI 机器人到办公 IM 这件事我前后折腾过不少次Copaw 算是其中让我觉得安装到飞书集成这条链路走得比较顺的一个。Copaw 本质上是一个把大模型能力接进飞书的机器人网关服务你把它部署在 Windows 机器上配置好模型接口和飞书应用就能在飞书里直接跟 AI 对话、让它按人设回消息、甚至把它接进群聊里做自动化处理。这篇指南会从环境准备、模型接入、飞书开放平台配置一直到启动联调、常见问题排查完整走一遍 Copaw 在 Windows 下的部署流程。无论你是刚接触 AI 应用部署的新手还是以前只玩过 Docker 跑 Nginx 的朋友只要照着下面的步骤来基本能在一两个小时之内把 Copaw 跑起来。1. 先搞清楚 Copaw 是干什么的1.1 Copaw 是什么一个连接飞书和大模型的网关很多朋友一听到部署 AI就以为是要自己训练模型其实是两码事。Copaw 这类项目做的事是把已经存在的模型能力比如本地 Ollama 拉下来的 Qwen或者云端 DeepSeek API包装成一个能听懂 IM 消息的服务。你不需要懂 transformer 结构也不需要写神经网络只需要把它当成一个消息中转站来理解。打个比方Copaw 就像一个餐厅前台飞书用户是客人大模型是后厨Copaw 负责收点单、把需求转成后厨能理解的格式、再把做好的菜端回给客人。后厨可能是本地 Ollama 这个自己家厨房也可能是 DeepSeek 这种外包食堂但前台Copaw的职责不变。具体到部署形态Copaw 会监听飞书事件回调收到消息后调用你配置的模型接口拿到回复再通过飞书机器人 API 发出去。整个过程不需要你自己去处理 WebSocket 握手、签名校验、消息格式转换这些脏活项目代码里已经帮你接好了。这也是我推荐新手用它入门 IM 机器人部署的原因你只需要关注配置而不是写连接代码。1.2 部署前先做三个决定动手之前把下面三个问题想清楚后面会少走很多弯路。第一个决定模型用本地还是云端。本地模型用 Ollama 跑优点是数据不出内网、没有按 token 计费的问题缺点是依赖显卡配置7B 模型在纯 CPU 机器上会比较吃力。云端 API 用 DeepSeek 这类服务优点是响应快、不需要好显卡缺点是每轮对话都要花钱虽然很便宜且对话内容会经过第三方服务。我个人建议机器带得起就用本地跑不动就直接上云端。第二个决定Copaw 用 Docker 跑还是裸机跑。Windows 下 Docker Desktop 是很成熟的方案能帮你隔离 Python 版本和依赖冲突但如果你的机器配置一般或者不想装 WSL2 那一套直接在系统里装 Python 然后pip install也完全可行。两者会在第二章详细对比。第三个决定飞书事件通道用长连接还是回调地址。飞书开放平台现在支持长连接模式本地部署不需要公网 IP这对家庭宽带用户来说简直是救命稻草。如果你有云服务器和备案域名也可以走 webhook 回调。在第四章我会强烈建议你先用长连接。2. Windows 环境准备给 Copaw 收拾一个能跑的地盘2.1 运行时和版本Python 3.10/3.11 最稳Copaw 基于 Python 开发所以先解决 Python 环境。Windows 下装 Python 我踩过一次坑从微软商店装的版本有时候 PATH 路径跟你预期不一致导致命令行里python指向了商店的别名而不是真 Python。更稳的做法是去官网下载安装包安装时务必勾选Add Python to PATH这一项。版本上建议装 3.10 或 3.11。很多 AI 项目对 Python 3.12 的支持会慢半拍某些依赖包在 3.12 下没有预编译 wheelpip 安装时会现场编译Windows 没有编译工具链就会直接报错。3.10/3.11 是当前兼容性最好的区间。装完之后在 PowerShell 里验证一下python --version pip --version如果提示找不到命令多半是 PATH 没配好。打开编辑系统环境变量把 Python 安装目录和Scripts子目录加进去然后重开终端再试。除了 Python还需要确认机器上有 Git。现在 Windows 自带 Git 的场景很少一般都要去 Git 官网下载安装安装时默认选项就行。后面拉取 Copaw 代码、更新版本都用得到。2.2 Docker 还是裸机Windows 下两种运行方式对比这里把两条路都讲清楚你按自己情况选。裸机方案直接在系统里安装依赖。适合配置一般的笔记本或者不想装 Docker Desktop 的人。缺点是 Python 环境容易越搞越乱——今天装 Copaw 的依赖明天装 Dify后天装别的项目版本冲突是必然的。我的做法是先用python -m venv venv建一个虚拟环境把 Copaw 装在里面跟系统全局 Python 隔离。激活方式.\venv\Scripts\Activate.ps1Docker 方案Windows 装 Docker Desktop 后Copaw 的依赖全部打进镜像里宿主机只需要有 Docker 引擎。环境隔离最彻底换机器迁移也方便。缺点是需要 WSL2 后端老机器开虚拟化可能有性能损耗。哪个更好如果你只是试玩、跑通流程裸机 venv 就够了没有额外学习成本。如果你想长期使用并且后面还可能部署其他 AI 工具直接上 Docker 是更省心的路。Docker 版本的docker-compose.yml大致长这样services: copaw: build: . container_name: copaw ports: - 8000:8000 env_file: - .env volumes: - ./data:/app/data restart: always注意env_file指向.envCopaw 的模型密钥、飞书密钥都放在这里。这样配置和代码分离以后改 key 就不用动容器。2.3 拿代码先读 README 再动手克隆代码之前先把仓库的 README 完整看一遍。Copaw 的 README 一般会写清楚 Python 版本要求、依赖安装方式、配置文件模板位置。这一步很多人会跳过然后卡在启动报错四处问人其实答案就在 README 里。克隆到本地git clone https://github.com/your-fork/copaw.git cd copaw进入目录后重点看这几个东西requirements.txtPython 依赖清单、.env.example环境变量模板、config/目录如果有。建议直接复制.env.example为.env后面在这个文件里填密钥而不是去改代码。还没完下一步是安装依赖。裸机方案执行pip install -r requirements.txt如果在国内网络环境下下载慢可以临时加-i https://pypi.tuna.tsinghua.edu.cn/simple换镜像源。这里顺带提醒一句依赖安装报错时别急着重装先看是哪个包报错很多情况下是某个包需要更高版本的 Python。3. 模型接入配置给 Copaw 装上大脑3.1 本地模型方案Ollama 安装与模型拉取Copaw 本身没有模型你得给它配一个大脑。本地方案我推荐 Ollama因为它把模型部署这件事简化到了极致。Windows 上安装 Ollama 就是下载安装包、双击、下一步装完会在托盘常驻一个服务。然后拉一个模型这里我以qwen2.5:7b为例ollama pull qwen2.5:7b首次拉大概要几个 G 的空间看网速等十几分钟。拉完先验证一下能不能正常对话ollama run qwen2.5:7b 你好能返回内容说明本地推理链路通了。这时 Ollama 默认监听在127.0.0.1:11434Copaw 的配置里指向这个地址就行。但有个细节很容易坑到人如果你把 Copaw 放在 Docker 容器里运行容器内访问宿主机的127.0.0.1是不通的。此时需要让 Ollama 监听所有网卡设置环境变量后重启 Ollama$env:OLLAMA_HOST0.0.0.0然后在窗口里运行ollama serve或者在 Ollama 的启动脚本里加上这个参数。不然你会在容器日志里看到一堆连接拒绝的报错。3.2 云端 API 方案DeepSeek 与 OpenAI 兼容接口没有好显卡不想跑本地模型的直接走云端 API。DeepSeek 是目前性价比很高的选择而且它提供 OpenAI 兼容接口这意味着 Copaw 只需要按 OpenAI 客户端的方式配置即可。先到 DeepSeek 开放平台注册账号、充值、创建 API Key然后把 Key 填进 Copaw 的.envOPENAI_API_BASEhttps://api.deepseek.com OPENAI_API_KEYsk-xxx MODEL_NAMEdeepseek-chat注意不同平台的 base URL 格式略有差异有的是https://api.deepseek.com有的是https://api.deepseek.com/v1。Copaw 的文档通常会写清楚用哪种。如果填错常见的表现是启动不报错但发消息给机器人时返回 401 或者 404。除了 DeepSeek任何支持 OpenAI 兼容格式的服务都可以配进来比如通义千问的兼容模式、本地 LLaMA 服务器等。这其实是 Copaw 的一个优势它不强绑某一家模型你想换模型就改三行配置的事。3.3 模型参数的调法配好模型之后还会遇到几个参数新手容易不知道填什么。解释几个常用的temperature控制回答的随机性0 到 1 之间。想让它严谨稳定就调低到 0.3想让它聊天更有发散性就 0.8。max_tokens单次回答的最大长度。别设太小不然回答到一半被截断对话体验很糟糕。system_prompt系统人设。这是 Copaw 里最有意思的配置你可以给机器人设定成专业运维助手小红书文案写手英语陪练Copaw 会带着这个人设去跟模型交互。我的建议是先不改这些高级参数用默认值跑通全流程再回来慢慢调。一次只改一个参数改完在飞书里发条消息测试观察差异别一次性全动。4. 飞书开放平台配置最容易翻车的环节4.1 创建自建应用并开通机器人能力飞书开放平台的配置是整个部署流程里最琐碎的一环逻辑不难但漏掉一步就前功尽弃。打开飞书开放平台开发者后台选择创建企业自建应用填应用名称和描述完成后进入应用详情页。在应用能力里找到机器人点击开通。开通后你会看到 App ID 和 App Secret 两个关键值App Secret 只在首次展示时能完整看到务必先复制到本地。这两个值后面要填到 Copaw 的.env中FEISHU_APP_IDcli_xxxx FEISHU_APP_SECRETxxxx我这里踩过一坑把 App ID 和 App Secret 当成一样的字段填反了结果一直报签名错误。如果启动日志里出现invalid signature或sign相关报错第一反应检查这两个值有没有填对。4.2 事件订阅为什么本地部署首选长连接飞书机器人要听到消息必须订阅事件。这里有两种接收方式回调地址和长连接。回调地址方式需要你把一个公网可访问的 URL 填进飞书后台。本地电脑没有公网 IP 的话就得去云服务器上转一道或者做内网穿透。对个人部署来说非常麻烦而且回调接口还得处理签名验证逻辑。长连接方式就友好得多飞书 SDK 在你的服务端主动建立一条 WebSocket 长连接事件通过这条连接直接推给 Copaw不需要任何公网入口。配置时在飞书后台事件订阅处选择使用长连接接收事件然后把.env里的事件类型配置成对应值即可。必须订阅的事件是im.message.receive_v1接收消息。飞书把所有事件类型列得很细新手容易在权限和事件之间来回切换搞不清楚哪个负责收消息。认准这个事件名把它的版本勾选上。另外飞书要求你在后台填写 Encrypt Key 和 Verification TokenCopaw 的.env里也有对应字段。这里要记住一个原则后台开了加密.env就必须配置相同的 Encrypt Key后台不加密.env里就留空。两边不一致时即使事件收到解密也会失败表现为机器人毫无反应。4.3 权限、版本发布与机器人可见范围有了事件订阅还不够机器人还需要调用飞书 API 发消息这涉及权限申请。在权限管理里添加消息相关权限常用的包括im:message读取消息内容im:message:send_as_bot以机器人的身份发送消息im:message.p2p_msg接收单聊消息im:message.group_at_msg接收群里 机器人的消息申请后最重要的动作是创建版本并发布。飞书的应用体系里能力配置和权限不是改了立刻生效的你需要到版本管理与发布里创建版本、提交发布。自建应用可以选择发布给组织内所有成员或指定成员至少发布给仅自己才能开始测试。我见过不少人配好了应用在后台测试事件也显示成功但飞书里跟机器人说话没反应最后发现就是没发布版本。机器人在发布之前根本不会出现在搜索结果和消息入口里。5. 启动服务与全链路联调5.1 首次启动日志里找线索配置全部就位后第一次在 Windows 上启动 Copaw。裸机方案在项目目录下执行python main.pyDocker 方案执行docker compose up -d启动后观察输出日志正常情况下应该能看到三件事配置加载完成、模型连接测试通过、飞书长连接建立成功。Copaw 的日志通常会把每个环节打出来看到类似connect to feishu long connection success的字段就说明飞书侧连通了。如果卡在某一步别急着关日志。大多数启动失败就三类依赖缺失报ModuleNotFoundError、密钥配置错误报Invalid param、网络不通报Connection开头的一串异常。按这个顺序排查最快。Windows 上的一个冷知识有些依赖在 Windows 下安装时会报编码错误因为控制台默认 GBK 编码日志里有 UTF-8 中文就没法显示。这时可以在启动前执行chcp 65001或者设置环境变量PYTHONIOENCODINGutf-8。不然日志会变成乱码看着像乱码的时候总怀疑哪里坏了。5.2 在飞书里跑通第一句话启动成功后去飞书里搜你的应用名进入单聊窗口给机器人发一句Hello或者你是谁。如果配置正确几秒内就能收到回复本地模型要看推理速度云端 API 会更快。群聊场景略有不同你得把机器人拉进群里然后发消息时必须 机器人不然机器人收不到消息。这是因为你订阅了im.message.group_at_msg事件它只推送群消息里 了机器人的那些。跑通第一句话之后建议测试几个不同的场景确认边界私聊发普通文本群里 机器人提问连续多轮对话看机器人是否记住上下文Copaw 一般有会话记忆窗口发一个空消息或只发图片看会不会报错我比较建议先只测文本。很多 IM 机器人对图片、文件消息的处理是缺失或受限的如果一上来就发图片测试遇到报错容易误判是部署问题。5.3 常驻后台三招让 Copaw 开机自启开发测试阶段开个终端窗口没问题但真要长期用总不能每次开机都手动启动。Windows 下有三个方案方案一任务计划程序。在 Windows 搜索任务计划程序创建任务触发器选登录时或启动时操作选启动程序程序填python参数填main.py的完整路径起始目录填项目目录。这个方案最简单不需要装任何第三方工具。方案二NSSM 注册成 Windows 服务。NSSM 是一个将普通命令行程序包装成 Windows 服务的工具。下载 nssm在管理员终端里执行nssm install Copaw然后在弹出的界面里填程序路径、参数和启动目录。注册后服务会随系统自动启动还可以设置崩溃自动重启。比任务计划程序更稳定。方案三Docker 的 restart 策略。如果你用的是 Docker 方案docker-compose.yml里已经写了restart: always。配合 Docker Desktop 的开机自启选项容器也会跟着系统起来。而且容器崩了会自动重启省心很多。三种方案我实际用下来任务计划程序适合刚入门NSSM 适合要上生产环境的朋友Docker 是最省心的。选哪种都行只要别每次手动起就行。6. 常见问题排查与避坑记录6.1 高频问题速查表整理一份我在部署 Copaw 及同类项目时实际遇到过的高频问题可以直接对照排查。症状可能原因解决办法飞书里发消息机器人没反应应用未发布版本 / 事件未订阅 / 长连接未建立检查后台是否创建版本并发布核对后台事件订阅是否选了im.message.receive_v1看启动日志是否显示长连接成功机器人回复验证失败或签名错误App ID / App Secret 填错到飞书后台重新查看注意 Secret 只在创建时完整展示若已丢失需重置启动报 ModuleNotFoundError依赖没装全 / Python 版本不符重新执行pip install -r requirements.txt确认 Python 是 3.10/3.11端口 8000 被占用之前有服务占用netstat -ano | findstr :8000找到 PID再taskkill /PID 进程号 /FDocker 启动失败WSL2 未启用 / Hyper-V 冲突检查 Docker Desktop 的 WSL2 后端设置wsl --status看状态本地模型回复特别慢7B/14B 模型超出机器算力换更小模型qwen2.5:3b或切换云端 API日志全是乱码Windows 控制台编码问题启动前执行chcp 65001或设置PYTHONIOENCODINGutf-8机器人能收到消息但没回复模型 API Key 失效 / 网络不通先 curl 测试模型接口确认模型侧可用再看 Copaw 日志里模型调用的报错6.2 几个比较隐蔽的坑最后说几个藏得比较深、不太容易在文档里看到的坑。坑一飞书后台的事件订阅和权限是两套系统。订阅了事件不等于机器人能发消息发消息需要单独的权限。只订阅事件不申请发送权限结果是机器人能收到你的消息但回复发不出去日志里会报permission denied。这个错误信息很容易让人误以为是 Copaw 的问题其实是权限没配置。坑二加密开关两边必须同步。飞书后台可以开关消息加密Encrypt Key一旦开启飞书推送的所有事件内容都是密文。Copaw 需要配置相同密钥才能解密。如果后台开了加密而.env里没填日志会报解密失败或乱码如果后台没开而.env里填了部分 SDK 也可能异常。最省心的做法本地部署这种非生产场景后台和.env都留空不加密等部署到云端再说。坑三群聊 机器人这个动作很重要。订阅im.message.group_at_msg后机器人只在被 时响应。如果你只是想测试机器人能不能在群里发言记得先把它拉进群再 它。忘了 会导致测试发出去了、机器人没反应很多人会误以为部署失败。其实这是事件类型决定的正常行为。坑四Windows 防火墙没收口。Fly 的机器人和 Ollama 都监听本地端口如果你自测正常、但局域网另一台设备要访问 Copaw 的 Web 管理面如果项目带的话需要到防火墙放行对应端口。这一步在开发机上可以用的时候不觉得换网络环境或重启防火墙后就莫名其妙不通了。排查思路永远先去控制面板 → 防火墙 → 允许应用通过防火墙看看。坑五Ollama 在 Windows 上的默认监听地址是 127.0.0.1。这在前文提到过如果你用 Docker 跑 Copaw容器里的网络栈和宿主机是隔离的localhost指向的是容器自己不是 Ollama。最保险的做法是查一下宿主机在局域网内的 IP把 Copaw 的模型地址配成http://宿主机IP:11434同时把 Ollama 的监听放宽到0.0.0.0。说实话这类项目的部署难度真的不高难点全在各种你以为配好了其实没配好的细节上。我个人实际操作下来飞书开放平台那一步占掉了整个部署时间的一半以上——主要就是权限、事件、版本发布这三件事来回折腾。最后再分享一个小技巧跑通之后先把.env备份到一个独立文件里标注好环境说明比如生产环境-DeepSeek还是测试环境-Ollama。AI 项目的配置项只会越来越多不做好备份和标注三个月后再登录飞书后台想改配置你大概率已经忘了当初填的是哪个密钥。