飞牛 NAS 部署 CowAgent 并开放局域网访问

环境：飞牛 NAS（主机名 fnnas，普通用户 FNNAS，Python 3.11）
CowAgent 源码位于 /root/CowAgent/，Web 控制台端口 9899
所有命令在 NAS 上以 root 运行（sudo -i）

CowAgent 即 chatgpt-on-wechat（命令名 cow，包名 cowagent），是一个可以把 AI 接入微信/飞书的聊天机器人框架，支持多模型后端（智谱 GLM、OpenAI 等）、技能扩展、Web 控制台等功能。飞牛 NAS 没有自带浏览器，Web 控制台默认只监听 127.0.0.1，本机访问不了，所以需要把监听地址改成 0.0.0.0，让局域网内的电脑/手机能通过浏览器访问。

本文从零开始记录完整部署流程：获取源码、安装依赖、初始配置、用 systemd 托管服务、开放局域网访问，最后附常见坑和速查命令。

为什么选源码部署

项目提供了一个 docker-compose.yml，但引用的预构建镜像只有 amd64 版本。飞牛 NAS 如果是 ARM 架构（aarch64），Docker 方式会触发平台不匹配警告——虽然可以通过 platform: linux/amd64 模拟运行，或本地 docker build 自建 arm64 镜像，但都比较折腾，性能也打折。

源码部署更直接：克隆代码、pip install -e . 装好就能用，改配置方便，后续装技能、改源码都即时生效。所以本次走的是源码 + editable 安装方式。

1. 获取 CowAgent

1.1 前置条件检查

飞牛 NAS（fnOS，Debian 系）自带 Python 3.11，先确认版本：

1
2

python3 --version
# 期望输出 Python 3.11.x

确认 git 可用（fnOS 默认带）：

1
2

git --version
# 期望输出 git version 2.x.x

确认 pip 可用：

1

python3 -m pip --version

如果 pip 不存在，用系统包管理器补上：

1

apt update && apt install -y python3-pip

如果 python3 -m venv 报错缺模块，装一下 venv 包：

1

apt install -y python3-venv

1.2 克隆源码

切到 root，克隆到 /root/CowAgent/：

1
2
3

sudo -i
git clone https://github.com/zhayujie/chatgpt-on-wechat.git /root/CowAgent
cd /root/CowAgent

如果你的 CowAgent 是定制 fork，换成对应的仓库地址即可。关键是源码最终在 /root/CowAgent/ 这个路径下。

1.3 创建虚拟环境并安装

建议建一个独立 venv，避免污染系统 Python：

1
2
3

python3 -m venv /root/CowAgent/venv
source /root/CowAgent/venv/bin/activate
pip install -U pip

editable 安装（-e 参数），这样改源码即时生效，cow 命令也能直接用：

1

pip install -e .

这一步会安装依赖（包括 itchat、requests、flask 等），耗时取决于网络，一般几分钟。

1.4 验证安装

1

cow --version

看到版本号输出即安装成功。也可以用 Python 方式验证：

1

python3 -c "import cowagent; print('ok')"

2. 初始配置

2.1 创建配置文件

CowAgent 的配置文件是 config.json，首次使用需要从模板复制一份：

1
2

cd /root/CowAgent
cp config-template.json config.json

如果仓库里没有 config-template.json，直接 vi config.json 手动创建，参考下面的完整示例。

2.2 关键字段说明

web_host 和 web_password 在模板里默认没有，需要手动加（第 3 节专门讲）。

2.3 最小可用配置示例

以下是接通智谱 GLM 并开放 Web 控制台的最小配置（省略了不相关字段）：

1
2
3
4
5
6
7
8
9
10
11
12

{
  "channel_type": "web",
  "cow_lang": "zh",
  "web_port": 9899,
  "web_host": "0.0.0.0",
  "web_password": "你的登录密码",
  "bot_type": "zhipu",
  "model": "glm-5-turbo",
  "zhipu_ai_api_key": "你的智谱key",
  "zhipu_ai_api_base": "https://open.bigmodel.cn/api/paas/v4",
  "agent_max_context_tokens": 50000
}

如果用 OpenAI 兼容接口，把 bot_type 改成 "openai"，用 open_ai_api_key / open_ai_api_base 替代智谱相关字段，model 填对应模型名。

2.4 填入 API key

拿到智谱 key 后，用 sed 写入（注意替换 你的智谱key）：

1

sed -i 's/"zhipu_ai_api_key": "YOUR_KEY"/"zhipu_ai_api_key": "你的智谱key"/' /root/CowAgent/config.json

或者直接 vi 编辑，找到 zhipu_ai_api_key 那行改掉。验证：

1

grep zhipu_ai_api_key /root/CowAgent/config.json

3. 开放局域网访问

默认配置没有 web_host 字段，因此监听 127.0.0.1，只能本机访问。需要在 config.json 里加两个字段：

• web_host: 0.0.0.0 —— 监听所有网卡
• web_password: 自己设一个登录密码

推荐做法：用 sed 一行插入

在 "web_port": 9899 前面插入 web_host 和 web_password：

1

sudo sed -i 's/"web_port": 9899/"web_host": "0.0.0.0","web_password": "你的密码","web_port": 9899/' /root/CowAgent/config.json

终端自动换行会把长命令断成两行导致报错。如果复制粘贴失败，改用反斜杠续行，或直接用 vi 手动编辑。

验证是否改成功：

1

grep web_host /root/CowAgent/config.json

看到 "web_host": "0.0.0.0" 即成功。

替代做法：vi 手动编辑

1

sudo vi /root/CowAgent/config.json

1. 找到 "web_port": 9899 那一行
2. 按 i 进入编辑模式
3. 在 "web_port" 前面加上 "web_host": "0.0.0.0", "web_password": "你的密码",
4. 按 Esc，输入 :wq 回车保存

飞牛防火墙放行

如果上一步做完仍然从局域网访问不了，检查 fnOS 防火墙是否放行了 9899 端口：

1
2
3
4
5

# 查看当前规则
iptables -L -n | grep 9899

# 没有的话手动放行
iptables -I INPUT -p tcp --dport 9899 -j ACCEPT

fnOS 大部分版本默认不拦局域网端口，这一步通常不需要。但如果你在飞牛 Docker 网络或虚拟接口环境下部署，可能需要手动放行。

4. 配置 systemd 托管

CowAgent 需要长期运行，最好交给 systemd 管理——开机自启、崩溃自动重启、日志统一收集。

4.1 创建服务文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

cat > /etc/systemd/system/cowagent.service << 'EOF'
[Unit]
Description=CowAgent (chatgpt-on-wechat)
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=/root/CowAgent
ExecStart=/root/CowAgent/venv/bin/python3 app.py
Restart=always
RestartSec=10
StandardOutput=append:/var/log/cowagent.log
StandardError=append:/var/log/cowagent.log

[Install]
WantedBy=multi-user.target
EOF

几个关键点：

• WorkingDirectory 设为 /root/CowAgent，确保 config.json 和源码能被找到
• ExecStart 用 venv 里的 Python，而不是系统 Python，确保依赖正确加载
• Restart=always + RestartSec=10：进程崩溃后 10 秒自动拉起，避免重启风暴
• 日志统一写到 /var/log/cowagent.log

4.2 启动并设置开机自启

1
2
3

systemctl daemon-reload
systemctl enable --now cowagent
systemctl status cowagent --no-pager

看到 active (running) 即成功。确认日志正常输出：

1

tail -f /var/log/cowagent.log

看到 Web 控制台启动、监听 0.0.0.0:9899 的日志行就对了。

4.3 日常管理命令

1
2
3
4
5
6
7
8
9
10
11

# 查看状态
systemctl status cowagent

# 重启（改完 config.json 后必须执行）
systemctl restart cowagent

# 停止
systemctl stop cowagent

# 看实时日志
tail -f /var/log/cowagent.log

如果暂时不想用 systemd，也可以用 screen 或 nohup 后台运行：

1 2 3 4 5 6 7

# screen 方式 screen -S cowagent cd /root/CowAgent && source venv/bin/activate && python3 app.py # 按 Ctrl+A 再按 D 脱离会话 # nohup 方式 nohup /root/CowAgent/venv/bin/python3 app.py > /var/log/cowagent.log 2>&1 &

这两种方式都不支持开机自启和崩溃重启，长期运行还是推荐 systemd。

5. 从电脑访问

先查 NAS 的局域网 IP：

1

hostname -I

然后在电脑/手机浏览器打开：

1

http://NAS的IP:9899

例如 NAS IP 是 192.168.1.100，就访问 http://192.168.1.100:9899，输入第 3 步设的 web_password 登录。

登录后就能在 Web 控制台里直接跟 AI 对话，也可以从这里安装/管理技能（cow skill install ...）。

如果页面打不开，依次排查：

1. systemctl status cowagent 确认服务在跑
2. grep web_host /root/CowAgent/config.json 确认是 0.0.0.0
3. hostname -I 确认 IP 没错
4. 浏览器和 NAS 在同一局域网（同网段）

常见坑

常用命令速查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 切到 root（CowAgent 在 /root 下，需要 root 权限）
sudo -i

# 查看配置
cat /root/CowAgent/config.json

# 改监听地址
sudo sed -i 's/"web_port": 9899/"web_host": "0.0.0.0","web_password": "你的密码","web_port": 9899/' /root/CowAgent/config.json

# 验证
grep web_host /root/CowAgent/config.json

# 查 NAS 局域网 IP
hostname -I

# 重启服务（改完配置后执行）
systemctl restart cowagent

# 查看服务状态
systemctl status cowagent

# 看实时日志
tail -f /var/log/cowagent.log

文件清单