### 引言：写小说，真的能交给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
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

3. 验证是否真的装上了

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

输入：

```
git --version
python --version
node --version
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/e0bfdac6ee169c1434dcd91aaf27cb45.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

如果 `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
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/75ba845a308780e5025882fce29eb402.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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


```
claude --version
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/20d1b3f761ecb8a5077a896a2b606b13.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

#### **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
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/62b7fdbfda1e31a916be3c0a159acd9c.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

#### 3.2 创建并激活虚拟环境


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


```
python -m venv .venv
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

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


```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy RemoteSigned -Force
.\.venv\Scripts\Activate.ps1
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

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

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


```
python -m pip install --upgrade pip
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/95771a4fa51b9e8313c1cde35604c2d2.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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


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

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


```
# 在仓库根（webnovel-writer）里
python -m pip install -r requirements.txt
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/4a72ec490f64c92cba6f8d7b9073096c.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

#### **常见问题**


##### 第一雷：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
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/68f5b4a1b945c1683de3f2d833157c73.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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


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


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

	- 	用记事本打开它。
		

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

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


![image](https://developer.qcloudimg.com/http-save/yehe-10809644/1bbaa591b0ce611308f3d36fe8ca5b9f.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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


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

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


```
Copy-Item -Path .env.example -Destination .env -Force
notepad .env
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

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


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

RERANK_BASE_URL=https://你的接口地址/v1
RERANK_MODEL=/你的重排模型名字
RERANK_API_KEY=你的另一个密钥填这里
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/4624331c3ab5f715782ac7bd5d99069d.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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

#### 获取API步骤


登录****[蓝耘 MaaS 平台](https://console.lanyun.net/#/register?promoterCode=18586cc762)****后，在MaaS平台找到 **API KEY** 菜单，点击 **创建 API KEY** 按钮，系统将为您生成一串唯一的密钥字符串。请妥善保存该密钥，后续配置步骤中将会用到。

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/827dfda46d5ed40f5b1b714dbf0dde64.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

#### **获取模型名称**


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

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

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/2b7d3caa184dab201ecc75812a399220.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

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


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

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

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

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


```
python -X utf8 .\webnovel-writer\scripts\webnovel.py --project-root . preflight
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/c21f6256416b931b2d4868560d13b885.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)​编辑

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

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


```
python -X utf8 webnovel-writer\scripts\webnovel.py init . "小说标题" "小说类型"。
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/d34b0d14acf7e483f5218c364aeedae4.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)​编辑

**拆解一下：**


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

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

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

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

	- 	`"现代都市"`：小说题材。
		


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

![image](https://developer.qcloudimg.com/http-save/yehe-10809644/cca39c9c202889e4f1546ecd047c988e.png)![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)​编辑

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


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

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

1. 添加市场源

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


```
claude plugin marketplace add lingfengQAQ/webnovel-writer --scope user
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)


	- 	安装插件
		


接着输入：


```
claude plugin install webnovel-writer@webnovel-writer-marketplace --scope user
```
![image](https://developer.qcloudimg.com/http-save/yehe-10809644/971f583f37ba4bea1091cc6529119849.gif)

看到成功提示后，这个神级外挂就彻底长在 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是最好用的键盘和笔，而你，永远是那个唯一的作者。

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

​

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

熬夜爆肝整理！手把手带你本地部署Claude最强“码字外挂”，从此告别卡文焦虑

全栈开发

人工智能

后端

开发工具

AI写作神器Webnovel-Writer保姆级安装教程，手把手教你搭建ClaudeCode插件环境，解决卡文难题。从Git、Python安装到RAG配置，详细步骤解决常见报错，让AI帮你完成小说创作。适合零基础用户，轻松实现自动码字、大纲生成和角色管理，提升写作效率。

聊天机器人

编译器

Windows

Python

GitHub

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

熬夜爆肝整理！手把手带你本地部署Claude最强“码字外挂”，从此告别卡文焦虑-腾讯云开发者社区-腾讯云

熬夜爆肝整理！手把手带你本地部署Claude最强“码字外挂”，从此告别卡文焦虑

熬夜爆肝整理！手把手带你本地部署Claude最强“码字外挂”，从此告别卡文焦虑

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐