Windows下部署Copaw：飞书AI机器人接入全流程指南

部署 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 下没有预编译 wheel，pip 安装时会现场编译，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.ps1

Docker 方案：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指向.env，Copaw 的模型密钥、飞书密钥都放在这里。这样配置和代码分离，以后改 key 就不用动容器。

2.3 拿代码：先读 README 再动手

克隆代码之前，先把仓库的 README 完整看一遍。Copaw 的 README 一般会写清楚 Python 版本要求、依赖安装方式、配置文件模板位置。这一步很多人会跳过，然后卡在启动报错四处问人，其实答案就在 README 里。

克隆到本地：

git clone https://github.com/your-fork/copaw.git cd copaw

进入目录后，重点看这几个东西：requirements.txt（Python 依赖清单）、.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:11434，Copaw 的配置里指向这个地址就行。

但有个细节很容易坑到人：如果你把 Copaw 放在 Docker 容器里运行，容器内访问宿主机的127.0.0.1是不通的。此时需要让 Ollama 监听所有网卡，设置环境变量后重启 Ollama：

$env:OLLAMA_HOST="0.0.0.0"

然后在窗口里运行ollama serve，或者在 Ollama 的启动脚本里加上这个参数。不然你会在容器日志里看到一堆连接拒绝的报错。

3.2 云端 API 方案：DeepSeek 与 OpenAI 兼容接口

没有好显卡不想跑本地模型的，直接走云端 API。DeepSeek 是目前性价比很高的选择，而且它提供 OpenAI 兼容接口，这意味着 Copaw 只需要按 OpenAI 客户端的方式配置即可。先到 DeepSeek 开放平台注册账号、充值、创建 API Key，然后把 Key 填进 Copaw 的.env：

OPENAI_API_BASE=https://api.deepseek.com OPENAI_API_KEY=sk-xxx MODEL_NAME=deepseek-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_ID=cli_xxxx FEISHU_APP_SECRET=xxxx

我这里踩过一坑：把 App ID 和 App Secret 当成一样的字段填反了，结果一直报签名错误。如果启动日志里出现invalid signature或sign相关报错，第一反应检查这两个值有没有填对。

4.2 事件订阅：为什么本地部署首选长连接

飞书机器人要"听到"消息，必须订阅事件。这里有两种接收方式：回调地址和长连接。

回调地址方式需要你把一个公网可访问的 URL 填进飞书后台。本地电脑没有公网 IP 的话，就得去云服务器上转一道，或者做内网穿透。对个人部署来说非常麻烦，而且回调接口还得处理签名验证逻辑。

长连接方式就友好得多：飞书 SDK 在你的服务端主动建立一条 WebSocket 长连接，事件通过这条连接直接推给 Copaw，不需要任何公网入口。配置时在飞书后台事件订阅处选择"使用长连接接收事件"，然后把.env里的事件类型配置成对应值即可。

必须订阅的事件是im.message.receive_v1（接收消息）。飞书把所有事件类型列得很细，新手容易在权限和事件之间来回切换，搞不清楚哪个负责收消息。认准这个事件名，把它的版本勾选上。

另外，飞书要求你在后台填写 Encrypt Key 和 Verification Token，Copaw 的.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.py

Docker 方案执行：

docker compose up -d

启动后观察输出日志，正常情况下应该能看到三件事：配置加载完成、模型连接测试通过、飞书长连接建立成功。Copaw 的日志通常会把每个环节打出来，看到类似connect to feishu long connection success的字段就说明飞书侧连通了。

如果卡在某一步，别急着关日志。大多数启动失败就三类：依赖缺失（报ModuleNotFoundError）、密钥配置错误（报Invalid param）、网络不通（报Connection开头的一串异常）。按这个顺序排查最快。

Windows 上的一个冷知识：有些依赖在 Windows 下安装时会报编码错误，因为控制台默认 GBK 编码，日志里有 UTF-8 中文就没法显示。这时可以在启动前执行：

chcp 65001

或者设置环境变量PYTHONIOENCODING=utf-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 及同类项目时实际遇到过的高频问题，可以直接对照排查。

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 项目的配置项只会越来越多，不做好备份和标注，三个月后再登录飞书后台想改配置，你大概率已经忘了当初填的是哪个密钥。