引言：写小说，真的能交给AI吗？

不知道从什么时候开始，我们这群写字的人，面对着闪烁的光标，脑海里有千军万马，指尖上却像灌了铅。

“卡文”——这两个字大概是所有网文作者、小说爱好者最怕的梦魇。你构思了宏大的世界观，设计了立体的人物，但在把脑海中的画面转化为文字时，那种词不达意的无力感，真的能让人抓狂。

最近，圈内悄悄传开了一个名字：Webnovel-Writer。

它不是一个简单的“你输入一句，我生成一段”的粗劣聊天机器人，而是一个专门为长篇小说设计的Claude Code 插件。它能理解你的大纲、记住你的设定、甚至通过RAG（检索增强生成）技术，在写到第50章时，依然能精准回忆起第3章埋下的伏笔。

听起来很美好对吧？但当你点开它的GitHub主页，看到那一堆英文文档和命令行代码时，是不是瞬间头皮发麻？“本地部署”、“Python虚拟环境”、“Claude Code CLI”……这些词劝退了90%的人。

别慌。今天这篇保姆级教程，是我熬夜踩坑、填平无数报错后整理出来的。全文没有一个多余的废步骤，所有代码都可以直接复制。 只要你跟着这篇指南走，哪怕你是零基础的纯小白，也能在自己的Windows电脑上，把这个“神仙码字外挂”完完整整地跑起来。

第一章：磨刀不误砍柴工——搭建你的底层环境

我们要在本地跑起来这个工具，首先得把地基打好。就像你要做一顿大餐，总得先把锅碗瓢盆和食材准备齐。

我们需要三个基础工具：Git（用来把代码从网上拉下来）、Python（这个插件运行的核心血液）、以及可选的Node.js。

1. 召唤 PowerShell

不要用普通的CMD了，那个黑框框太老土。我们在Windows搜索栏里直接搜“PowerShell”，一定要右键，选择“以管理员身份运行”。为什么要管理员？因为Windows的权限机制很古怪，有时候你不给它管理员权限，它就暗中给你使绊子，安装到一半突然罢工。

2. 一键安装三件套

打开蓝色的管理员窗口后，逐行复制下面这三行命令，每复制一行，敲一下回车，喝口水的功夫它就装好了：

# 安装 Git（必须，用来下载代码）
winget install --id Git.Git -e --source winget

# 安装 Python 3.11（千万别装老版本，也别追新装3.13，3.11最稳）
winget install --id Python.Python.3.11 -e --source winget

# （可选）安装 Node.js LTS
winget install --id OpenJS.NodeJS.LTS -e --source winget

避坑指南：如果提示“找不到包”，说明你的winget源有点卡，先运行 winget search python 看看能不能搜到东西。

3. 验证是否真的装上了

关掉当前的PowerShell，重新打开一个新的（这一步极其重要，不重启的话系统记不住你刚装的软件）。

输入：

git --version
python --version
node --version

如果 python 不存在，试 py --version。安装后打开一个新的 PowerShell 窗口以刷新 PATH（如果已安装仍提示未找到，请重启或检查 PATH）。

第二章：唤醒魔法中枢——安装并登录 Claude Code

Webnovel-Writer 不是一个独立的软件，它是寄生在 Claude Code 里面的一个“灵魂插件”。所以，你必须先把 Claude Code 这个宿主请到你的电脑里。

2.1 一键召唤 Claude Code

还是在PowerShell里，复制这行神秘代码，回车：

irm https://claude.ai/install.ps1 | iex

安装后运行 claude（进入交互或查看版本）：

claude --version

2.2 登录与权限预警

装完后，输入 claude 试试。接着，最关键的一步来了：登录！ 在交互界面里输入 /login，或者在外面执行 claude auth login。这时候它会弹出一个浏览器页面，让你用Anthropic账号授权。

说句实在话（一定要看）：

Claude Code 不是免费的午餐。你要完整使用它的插件功能，你的 Claude 账号必须是 Pro、Max、Teams 或者企业版。如果你只是白嫖的免费账号，到了这一步或者后面装插件的时候，大概率会报权限错误的。别觉得是被骗了，这是官方的规矩，建议直接升级Pro，为了你的写作效率，这钱花得值。

第三章：为你的小说建一个“无菌病房”——克隆与虚拟环境

如果你直接把代码下下来就跑，大概率会把你自己电脑原本的Python环境搞得一团糟。我们要养成好习惯，给它建一个“虚拟环境”。

3.1 把代码拉到本地

在PowerShell里，我们切到你的常用盘符（比如C盘或者D盘）：

cd $HOME
git clone https://github.com/lingfengQAQ/webnovel-writer.git
cd webnovel-writer

这时候，你的文件夹里就有了一整套Webnovel-Writer的源码。

3.2 创建并激活虚拟环境

在刚才的 webnovel-writer 文件夹路径下，执行：

python -m venv .venv

这就像是在这个文件夹里建了一个与世隔绝的小房间。

接下来，我们要走进这个房间（激活虚拟环境）：

Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned -Force
.\.venv\Scripts\Activate.ps1

排雷时间： 很多朋友在执行第二行的时候，屏幕上会爆出一大堆红字报错（这就是文档里提到的那张图）。别慌，这根本不是你做错了，而是Windows默认不允许运行脚本。第一行代码就是用来临时“贿赂”一下Windows安全机制的，只对当前窗口有效，绝对安全。执行完第一行再执行第二行，红字就消失了。

激活成功后，你会发现命令行最前面多了一个 (.venv) 的绿色小帽子。看到它，就说明你进对了房间。

顺便把里面的安装工具升级一下：

python -m pip install --upgrade pip

第四章：渡劫时刻——安装依赖与“连环雷”排雷指南

这是整个安装过程中最容易让人崩溃的一步，但跟着我的节奏，你能丝滑通关。

在带有 (.venv) 小帽子的窗口里，执行：

# 在仓库根（webnovel-writer）里
python -m pip install -r requirements.txt

然后，就是漫长的等待。但现实往往不完美，你很可能会遇到以下三大经典报错：

常见问题

第一雷：C++ 编译器缺失报错

安装报错缺编译器：Windows 上某些包需要 C++ 构建工具，按提示安装 “Build Tools for Visual Studio” 或使用 wheel 版本。

第二雷：网络超时 / 代理报错

安装条走到一半，突然卡死不动，或者提示 ReadTimeout。 怎么破： 如果你开了翻墙软件（梯子/代理），很多时候会导致终端的网络冲突。最简单粗暴的方法：暂时关掉你的全局代理，或者使用国内清华大学的镜像源：

python -m pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

第三雷：watchdog 版本地狱（必看！）

如果你顺利避开了前两雷，很可能在这里翻车。安装快结束时，突然报错说 watchdog 的版本不对。 怎么破： 这是原作者代码里的一个小疏忽。不要慌，按我说的做：

1. 打开你的文件夹，找到这个路径：\webnovel-writer\webnovel-writer\dashboard\requirements.txt

2. 用记事本打开它。

3. 找到里面的 watchdog>=5.0.0，手动把 5.0.0 改成 4.0.0，也就是变成 watchdog>=4.0.0。

4. 保存文件，回到PowerShell，重新运行一遍那个 pip install -r requirements.txt。 搞定！这一步绝对能救你一命。

第五章：注入灵魂——配置你的专属 AI 记忆库

到了这里，代码已经在你电脑里了，但它还像个失忆症患者。我们需要给它注入“记忆”——这就是 RAG 环境变量的配置。

在你的 webnovel-writer 文件夹里，找到一个叫 .env.example 的文件。 在PowerShell里输入：

Copy-Item -Path .env.example -Destination .env -Force
notepad .env

这时候会弹出一个记事本，这就是配置面板。你需要把里面的内容替换成你自己的 API。

最少要填这6项（别漏掉任何一个）：

EMBED_BASE_URL=https://你的接口地址/v1
EMBED_MODEL=/你的嵌入模型名字
EMBED_API_KEY=你的密钥填这里

RERANK_BASE_URL=https://你的接口地址/v1
RERANK_MODEL=/你的重排模型名字
RERANK_API_KEY=你的另一个密钥填这里

科普一下： Embedding 是用来把你的小说文字变成AI能懂的“向量坐标”的，Rerank 是用来在几十万字里精准找出相关段落的。这两个东西配好了，你的AI写手就有了过目不忘的本领。填好后保存关闭。

获取API步骤

登录蓝耘 MaaS 平台后，在MaaS平台找到 API KEY 菜单，点击 创建 API KEY 按钮，系统将为您生成一串唯一的密钥字符串。请妥善保存该密钥，后续配置步骤中将会用到。

获取模型名称

在蓝耘 MaaS 平台的名广场页面，找到您希望使用的模型，记录其完整的模型标识名称。

示例模型名称：/maas/deepseek-ai/DeepSeek-V3.2

第六章：破壳新生——初始化你的第一部作品

万事俱备，只欠东风。现在我们要真正让这个工具为你服务了。

千万别直接盲干！ 文档里有一张很典型的报错图：很多人直接跟着网上的教程输入 python ... init，结果被无情报错，提示缺少参数。

正确的姿势是，你需要告诉它三个核心信息：在哪建、叫什么、写什么类型。

在你的PowerShell里（确保还在带有 .venv 的环境中），输入以下格式：

python -X utf8 .\webnovel-writer\scripts\webnovel.py --project-root . preflight

（README 建议使用 python -X utf8 "<CLAUDE_PLUGIN_ROOT>/scripts/webnovel.py" --project-root "<WORKSPACE_ROOT>" preflight，这里我们直接指向本地脚本。）

如果遇到下图中的问题，使用

python -X utf8 webnovel-writer\scripts\webnovel.py init . "小说标题" "小说类型"。

拆解一下：

• python -X utf8：防止中文乱码的护身符。

• webnovel-writer\scripts\webnovel.py init：执行初始化动作。

• .：代表在当前文件夹建项目（你也可以写具体路径）。

• "我的霸道总裁"：你的小说名字（一定要加引号）。

• "现代都市"：小说题材。

回车后，如果你看到它默默地生成了几个文件夹，没有任何红字报错，那么，恭喜你，你的AI写作帝国，在这一刻奠基了！

第七章：连接大脑——在 Claude Code 中挂载插件

前面做的都是本地铺垫，现在我们要把它和最聪明的大脑（Claude Code）连起来。

确保你之前已经登录了 Claude Code。在任意你喜欢的文件夹打开终端，输入 claude 进入交互界面。

1. 添加市场源

在Claude的对话栏里，直接输入：

claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user

1. 安装插件

接着输入：

claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user

看到成功提示后，这个神级外挂就彻底长在 Claude Code 身上了。

第八章：见证奇迹的时刻——如何使用这套终极武器

现在，你可以开始享受你的成果了。把Claude Code的工作目录切换到你刚才初始化小说的那个文件夹，然后在对话框里，你可以像发号施令一样使用以下“魔法咒语”：

• /webnovel-init：如果你换了新电脑，或者想重新在当前目录初始化，用这个。

• /webnovel-plan 1：让AI根据你给的设定，开始生成第一卷的详细大纲。它的逻辑能力会让你惊艳。

• /webnovel-write 1：这是全场最高潮的命令！ 输入它，AI就会根据大纲，结合你在RAG里注入的世界观，开始自动码字。你可以看着它一行行吐出细腻的描写、流畅的对话。

• /webnovel-review 1-5：写完了第1到第5章？让它自己当自己的主编，帮你做“毒点”排查和文笔润色。

• /webnovel-query 角色名：写到一半忘了某个配角的性格设定？直接问它，它能瞬间从你之前的设定里把资料拽出来。

(注：如果你想看一个炫酷的可视化面板，可以输入 /webnovel-dashboard，它会启动一个网页后台，不过核心的码字体验还是在命令行交互里最爽。)

结语：工具的尽头，依然是你的故事

写到这儿，这篇长达几千字的保姆教程终于到了尾声。

从安装环境、解决红色报错、修改隐藏的配置文件，到最终看着AI为你写下第一行小说，这个过程或许有些折腾。但相信我，当你第一次使用 /webnovel-write，看着它完美延续你的思路，写下那些你苦思冥想才组织好的长句时，你会觉得这几小时的折腾，值回票价。

但最后，我还是想说句题外话。

Webnovel-Writer 再强大，它也只是一个“外挂”。它能帮你解决遣词造句的疲惫，能帮你管理庞大复杂的人物关系网，能帮你克服面对空白文档的恐惧。但是，故事的核——那个让你自己都感动到落泪的冲突，那个反常规的脑洞，依然只存在于你的脑海里。

AI是最好用的键盘和笔，而你，永远是那个唯一的作者。

希望这篇排雷指南能帮到你。如果在安装过程中遇到了其他奇奇怪怪的问题，欢迎在公众号后台留言，我会尽量帮你解答。去写你的旷世之作吧！