1. 项目概述

如果你尝试过用大模型写小说，尤其是长篇连载，大概率会遇到一个共同的困境：生成一两章内容后，故事就开始失控。角色性格漂移、世界观设定前后矛盾、情节逻辑断裂……你仿佛在和一个记忆力只有七秒的“金鱼”合作，每次对话都得从头解释一遍“我们是谁、我们在哪、我们要干什么”。NovelClaw 正是为了解决这个痛点而生的。它不是另一个简单的“提示词包装器”，而是一个专为长篇叙事设计的、可检查、可控制、具备记忆能力的结构化写作工作空间。

简单来说，NovelClaw 把写长篇小说的过程，从一个“一次性提交巨型提示词并祈祷好运”的黑盒事件，转变为一个持续进行的、可视化的、可迭代的工程项目。它围绕章节草稿、可检查的运行状态、手稿审阅和记忆感知的写作控制来构建整个工作流。这意味着，作为作者，你不再只是故事的“发起者”，而是整个创作过程的“架构师”和“项目经理”，能够清晰地看到故事是如何被一步步构建起来的，并在任何节点进行干预和调整。

这个项目特别适合两类人：一是严肃的网文作者或小说创作者，他们需要工具来维持数十万甚至上百万字作品的连贯性；二是对可解释AI、多智能体系统或创意工作流感兴趣的开发者与研究者，NovelClaw 提供了一个绝佳的、贴近真实需求的工程实践样本。

2. 核心设计理念：从“生成”到“工程”

为什么传统的“提示词+续写”模式在长篇创作中会失灵？其根本原因在于，大语言模型本质上是无状态的。每次交互，模型都基于当前输入的上下文（通常有长度限制）进行计算，缺乏一个持久、稳定、可编辑的“项目状态”来锚定整个故事宇宙。NovelClaw 的设计哲学，就是为长篇创作引入“工程化”的思维。

2.1 状态持久化：为故事建立“数据中心”

在软件工程中，我们有数据库来持久化应用状态。在NovelClaw里，这个“数据库”就是一系列结构化的“记忆库”和“运行产物”。项目将创作过程中的关键状态明确分离并持久化：

  • 角色视图与世界观面板 ：不再是隐藏在对话历史里的只言片语，而是有独立编辑界面的结构化数据。你可以随时查看并修改主角的性格特征、角色的关系图谱，或者世界的物理法则、社会结构。
  • 故事板 ：相当于项目的“产品路线图”。它可视化地展示了章节之间的结构、情节的起承转合，让你对整体叙事脉络一目了然。
  • 记忆库 ：这是NovelClaw的“智能”核心。它不是一个黑箱，而是一个可编辑的“知识库”。系统会自动将关键情节、角色决策、环境细节等提炼并存入记忆库，在后续章节生成时，这些记忆会被作为上下文的一部分喂给模型，确保叙事的连续性。更重要的是，你可以直接编辑这些记忆条目，从而“修正”AI对故事的理解。

这种设计将创作从一次性的“灵感迸发”，转变为基于明确“设计文档”的迭代开发。你的每一次修改和调整，都作用在清晰的状态上，而不是与一个模糊的、易失的对话历史搏斗。

2.2 可观察性：打开AI创作的“黑箱”

另一个工程化的重要体现是“可观察性”。在传统方式下，你输入提示词，等待，然后得到一段文本。中间发生了什么？模型是如何“思考”的？为什么这里的情节会这样发展？你一无所知。

NovelClaw 将整个生成过程透明化。每一次“运行”都会产生详尽的日志和中间产物：

  • progress.log ：这是运行过程的“飞行记录仪”。它会记录关键事件，如 global_outline （全局大纲持久化）、 chapter_outline_ready （章节大纲就绪）、 memory_snapshot （记忆快照更新）等。通过阅读这个日志，你可以精确知道当前任务进行到了哪一步。
  • worker.log ：更底层的执行日志，有助于开发者或高级用户进行问题诊断。
  • 章节输出文件 ：每一章生成的原始文本都会被单独保存，方便对比和版本管理。
  • 任务详情页面 ：在Web界面上，你可以实时查看任务状态、进度百分比，并直接访问上述所有日志和文件。

这种可观察性带来了控制力。当生成结果不符合预期时，你不再需要盲目地调整提示词重试，而是可以像调试程序一样，检查“运行时”的状态，定位问题环节（是记忆提取有误？还是大纲规划不合理？），然后进行针对性的调整。

2.3 人机协同的工作流：作者始终是“导演”

NovelClaw 没有试图用AI完全取代作者，而是构建了一个“人在回路中”的高效协同环境。工作流被设计成一个清晰的循环：

  1. 进入与配置 ：通过统一的入口选择模式，配置好AI模型提供商（如OpenAI、Claude等）。
  2. 会话与构思 ：在聊天界面，你可以像与编剧助理讨论一样，抛出故事前提、讨论人物设定、细化章节要求。这个过程是开放和探索性的。
  3. 移交与生成 ：当构思成熟，你可以将会话内容“移交”给正式的创作流程。此时，NovelClaw的多智能体系统开始工作，根据当前故事状态（记忆、大纲）生成具体的章节内容。
  4. 检查与调整 ：在生成过程中或完成后，你可以立即在手稿界面审阅内容，在故事板调整结构，在记忆库修正认知。这些调整会立刻影响后续的生成。
  5. 继续与迭代 ：基于调整后的状态，回到聊天界面或直接触发续写，开始下一个循环。

在这个流程中，AI承担了高强度的“写作”和“记忆管理”劳动，而作者则专注于更高层次的“创意决策”和“质量把控”。作者始终手握“最终剪辑权”。

3. 架构深度解析：多智能体如何协同写作

NovelClaw 的威力很大程度上源于其背后精心设计的多智能体架构。它不是一个单一的、庞大的提示词工程，而是一组各司其职的“AI专家”组成的虚拟写作团队。理解这个架构，能帮助你更好地驾驭这个工具。

3.1 核心组件与数据流

整个系统的核心是 apps/novelclaw/ 目录下的应用。它主要包含以下几个关键部分，数据在其间流动：

  1. Web工作空间 (Frontend + FastAPI Backend) ：提供用户交互的所有界面，包括聊天、故事板、手稿、记忆库等。它接收用户指令，并将其转化为后台任务。
  2. 任务队列与调度器 ：负责管理并发的写作任务。当你发起一个“撰写下一章”的请求时，它会被包装成一个任务放入队列，确保系统资源被有序使用。
  3. 智能体执行引擎 ：这是“虚拟写作团队”的大脑。一个典型的章节生成任务可能会按顺序激活以下智能体：
    • 规划智能体 ：基于当前故事大纲和记忆，规划本章的核心冲突、情节转折点和情感基调。
    • 记忆检索与融合智能体 ：从可编辑的记忆库中，检索与本章相关的角色信息、世界观设定、过往情节关键点，并将其整理成一份紧凑的“上下文备忘单”。
    • 写作智能体 ：接收规划要点和记忆上下文，负责生成具体的叙事文本。它可能会进一步拆解为“场景描写智能体”、“对话生成智能体”等更细粒度的模块。
    • 一致性检查智能体 ：对生成的草稿进行快速扫描，检查是否存在与记忆库明显矛盾的地方（例如，角色的眼睛颜色前后不一致）。
  4. 状态存储层 ：包括SQLite数据库（ app.db ）和文件系统。所有结构化的状态（会话、任务记录、记忆条目）存入数据库；所有运行产物（日志、生成的章节文本）存入对应的运行目录（ runs/<run_id>/ ）。

这个架构的优势在于“解耦”和“可观察”。每个智能体负责一个相对独立、定义清晰的任务，其输入输出都可以被记录和检查。如果某一章的角色对话写得不好，你可以去检查“写作智能体”收到的输入（规划和记忆）是否准确，从而定位问题是出在前期规划，还是出在写作执行本身。

3.2 “记忆”的实现机制

“记忆”是NovelClaw的灵魂，其实现远比简单的“向量数据库检索”要复杂。它是一个分层、结构化的系统：

  • 基础层：向量检索 ：对于非结构化的文本记忆（如一段关于某个地点的描述），系统会使用嵌入模型将其向量化，存入向量数据库。在需要相关记忆时，通过语义相似度进行检索。
  • 结构层：属性数据库 ：对于高度结构化的信息（如角色的姓名、年龄、外貌特征、关键关系），系统将其作为属性存储在关系型数据库或结构化JSON中。这种记忆的查询是精确和快速的。
  • 逻辑层：记忆快照与摘要 ：在关键情节节点（如一章结束时），系统会触发“记忆快照”流程。一个专门的智能体会分析刚生成的内容，提取出 新增的、重要的、对后续剧情有影响的事实 ，并将其以结构化的方式（例如：“角色A在章节3中得知了秘密B，这导致他对角色C产生了怀疑”）写入记忆库。这个过程不是简单的原文存储，而是信息的提炼和抽象。
  • 控制层：人工编辑界面 ：所有自动生成的记忆条目，都可以在 Memory Banks 界面中被作者查看、编辑、删除或补充。这是作者纠正AI认知偏差、强化叙事重点的直接手段。

这种混合记忆系统，既保证了AI能回忆起相关的细节（通过向量检索），又能确保关键叙事逻辑的精确传递（通过结构化记忆和逻辑摘要）。

3.3 与Portal、MultiAgent模块的协作

项目仓库中除了核心的 novelclaw ，还有 auth-portal 和 multiagent 两个应用，它们共同构成了一个完整的生态：

  • Portal ( auth-portal ) ：这是一个“干净”的公共入口。它的主要职责是模式选择和路由，将用户引导至核心的NovelClaw工作空间。这种设计将公开的、无需认证的入口逻辑与核心的、可能涉及敏感API密钥和数据的写作工作空间分离开，提升了项目的安全性和部署整洁度。
  • MultiAgent ( multiagent ) ：这是一个可选的“快速构思通道”。你可以把它理解为一个“头脑风暴会议室”。当你只有一个模糊的想法时，可以在这里利用多个AI智能体进行快速的角色碰撞、情节发散和创意筛选，快速产出一个故事雏形或丰富的人物设定。当构思成熟后，你可以将这个“雏形”无缝导入到NovelClaw中，开始严肃、结构化的长篇创作。它和NovelClaw共享相似的多智能体架构，但目标更侧重于创意发散而非严谨的连续性写作。

在实际使用中，典型的路径是：通过Portal入口 ( http://localhost:8010/select-mode ) 选择进入NovelClaw，然后在其内部完成所有核心写作工作。MultiAgent 是一个在你需要时的强大辅助工具。

4. 从零开始的实战部署与配置指南

理论说得再多，不如亲手跑起来。下面我将以最推荐的Docker方式，带你从零开始部署并配置一个属于你自己的NovelClaw工作空间。我会解释每一个步骤背后的原因，并分享一些部署中容易踩的坑。

4.1 环境准备与Docker部署

使用Docker是避免环境依赖地狱的最佳实践，它能确保你在Windows、macOS或Linux上获得完全一致的运行体验。

第一步：获取代码与前置检查 

git clone https://github.com/iLearn-Lab/NovelClaw.git
cd NovelClaw

首先，检查项目根目录下是否存在 docker-compose.yml 文件。这个文件定义了NovelClaw（以及Portal和MultiAgent）三个服务的容器化运行方式。如果不存在，你可能克隆了错误的分支或版本。

第二步：配置环境变量文件 这是最关键的一步，错误配置会导致服务无法启动。三个服务都需要独立的配置。

# 复制环境变量示例文件到实际位置
cp .env.auth-portal.example apps/auth-portal/.env
cp .env.multiagent.example apps/multiagent/.env
cp .env.novelclaw.example apps/novelclaw/.env

现在，你需要编辑这三个 .env 文件。最重要的配置是AI模型的API密钥。以 apps/novelclaw/.env 为例，找到类似以下内容：

# 示例：配置OpenAI
OPENAI_API_KEY=sk-your-actual-openai-api-key-here
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4-turbo-preview

# 示例：配置Anthropic (Claude)
ANTHROPIC_API_KEY=your-actual-anthropic-api-key-here
ANTHROPIC_MODEL=claude-3-opus-20240229

关键提示 ：你不需要配置所有提供商。只需配置你计划使用的一个或几个。NovelClaw 的模型管理界面会读取这些配置，并提供下拉列表供你选择。请务必确保密钥正确，且对应的模型名称与提供商官方文档一致。 OPENAI_BASE_URL 字段也支持配置为其他兼容OpenAI API的代理服务地址。

第三步：启动Docker服务 在项目根目录下，执行：

docker-compose up -d

-d 参数代表“后台运行”。这条命令会执行以下操作：

  1. 根据 docker-compose.yml 拉取所需的Python等基础镜像。
  2. 为每个服务（portal, multiagent, novelclaw）构建或启动独立的容器。
  3. 将容器内的服务端口映射到宿主机的对应端口（默认是8010, 8011, 8012）。
  4. 将容器内的数据卷（如数据库文件、运行日志）挂载到宿主机的对应目录，确保数据持久化，不会随容器销毁而丢失。

第四步：验证服务状态 启动完成后，运行 docker-compose ps 查看所有容器的状态。正常情况下，三个服务的状态都应为 Up 。你也可以通过查看日志来排查问题：

# 查看novelclaw服务的日志
docker-compose logs -f novelclaw
# 查看所有服务的日志
docker-compose logs -f

如果看到数据库初始化、FastAPI应用启动成功（如 Uvicorn running on http://0.0.0.0:8020 ）等字样，说明服务启动正常。

第五步：访问工作空间 打开浏览器，访问入口： http://localhost:8010/select-mode 。 你会看到一个简单的模式选择页面。点击进入 NovelClaw ，它将会自动跳转到核心工作空间的主仪表盘： http://localhost:8012/dashboard 。

至此，Docker部署完成。你可以随时使用 docker-compose down 停止并移除所有容器，使用 docker-compose up -d 再次启动，你的数据（如已创建的故事、记忆库）会因卷挂载而得以保留。

4.2 手动本地部署详解

如果你对Docker不熟悉，或者需要在生产环境进行更定制化的部署，手动部署是必须掌握的技能。以下步骤基于项目提供的脚本，但我会解释其背后的原理。

第一步：Python环境准备 NovelClaw 要求 Python 3.10+。建议使用虚拟环境隔离依赖。

# 创建并激活虚拟环境（以Linux/macOS为例）
python3.10 -m venv .venv
source .venv/bin/activate
# Windows系统使用：.venv\Scripts\activate

第二步：使用项目脚本快速初始化 项目提供了强大的PowerShell脚本（Windows）或Shell脚本（Linux/macOS）来自动化繁琐的步骤。以Windows为例：

# 1. 停止可能占用端口的旧进程，并写入默认的环境配置文件
.\scripts\setup-local-env.ps1 -Overwrite

# 2. 创建一个共享的虚拟环境，并安装所有子应用（portal, multiagent, novelclaw）的依赖
.\scripts\bootstrap-shared-venv.ps1

# 3. 使用共享虚拟环境，启动所有三个本地服务
.\scripts\start-all-local.ps1 -UseSharedVenv

执行后，脚本会依次启动三个服务，并输出访问地址。这是最快捷的本地启动方式。

第三步：理解脚本背后的手动流程 如果脚本执行失败，或者你想理解其原理，可以手动执行以下步骤：

  1. 安装依赖 ：每个 apps/ 下的子应用都有 requirements.txt 。需要分别安装。 
    cd apps/novelclaw
pip install -r requirements.txt
cd ../multiagent
pip install -r requirements.txt
cd ../auth-portal
pip install -r requirements.txt
cd ../..
  2. 配置环境变量 ：同Docker部署，需要手动创建并编辑三个 .env 文件。
  3. 启动应用 ：每个FastAPI应用都可以用Uvicorn独立启动。例如启动NovelClaw： 
    cd apps/novelclaw
uvicorn main:app --host 0.0.0.0 --port 8020 --reload
    --reload 参数便于开发时代码热重载。生产环境应移除。Portal和MultiAgent默认分别监听8010和8011端口，启动命令类似。

第四步：生产环境部署考量 对于希望长期、稳定运行的服务，需要考虑：

  • 反向代理 ：使用Nginx或Caddy作为反向代理，处理SSL/TLS（HTTPS）、静态文件服务和负载均衡。项目在 infra/nginx/ 下提供了示例配置。
  • 进程管理 ：使用 systemd (Linux) 或 Supervisor 来管理Uvicorn进程，确保服务崩溃后能自动重启。 infra/systemd/ 下有服务单元文件示例。
  • 数据库 ：目前默认使用SQLite，适合轻量级使用。如果团队协作或数据量巨大，可以考虑迁移到PostgreSQL，但这需要修改后端的数据库连接代码。
  • 资源隔离 ：将三个服务（portal, multiagent, novelclaw）部署在不同的子域名或路径下，并通过反向代理统一管理。

4.3 核心配置项详解与调优

要让NovelClaw发挥最佳性能，除了API密钥，还有一些配置值得关注。这些配置通常位于各应用的 .env 文件或 config.py 中。

  1. 模型与推理参数 ：

    # 在novelclaw的.env中，你可以为不同任务指定不同的默认模型
PLANNING_MODEL=gpt-4-turbo-preview  # 规划智能体使用的模型，需要较强的逻辑分析能力
WRITING_MODEL=gpt-4-turbo-preview   # 写作智能体使用的模型，需要优秀的文笔和创造力
SUMMARY_MODEL=gpt-3.5-turbo         # 摘要和记忆提炼智能体，对成本敏感，可用能力稍弱的模型

# 控制生成“随机性”和“专注度”的温度参数
PLANNING_TEMPERATURE=0.7  # 规划时可以稍高，鼓励创意
WRITING_TEMPERATURE=0.9   # 写作时可以更高，使文风更生动
SUMMARY_TEMPERATURE=0.3   # 总结记忆时需要非常确定和准确，温度应设低

    通过为不同任务分配合适的模型和参数，可以在效果和成本间取得最佳平衡。

  2. 记忆系统参数 ：

    # 控制记忆检索的相关性阈值和数量
MEMORY_SEARCH_TOP_K=5           # 每次检索返回最相关的5条记忆
MEMORY_SIMILARITY_THRESHOLD=0.7 # 相似度低于0.7的记忆条目将被过滤，避免引入不相关信息

# 控制记忆快照的触发频率和摘要长度
MEMORY_SNAPSHOT_CHAPTER_INTERVAL=1  # 每写完1章就触发一次记忆快照
MEMORY_SUMMARY_MAX_LENGTH=500       # 单条记忆摘要的最大长度（字符）

    调整这些参数可以影响AI对过往故事的“记忆力”。 TOP_K 太大可能导致上下文过长且包含噪音；阈值太高可能导致检索不到足够相关的记忆。

  3. 任务队列与性能 ：

    # 控制并发任务数，避免超过API速率限制或本地资源耗尽
MAX_CONCURRENT_TASKS=2
# OpenAI等提供商对每分钟/每天的请求数和Token数有限制，并发数过高会导致频繁报错。

# 任务超时设置（秒）
TASK_TIMEOUT=600  # 单个任务最长运行10分钟，防止卡死

    对于个人使用， MAX_CONCURRENT_TASKS=1 是最稳妥的。如果是团队使用或调用本地部署的大模型，可以适当调高。

5. 核心工作流实战：创作你的第一个故事

环境搭好了，现在让我们真正用NovelClaw来创作一个短篇故事，体验其完整的工作流。我将以一个简单的“科幻悬疑”故事为例。

5.1 第一步：初始化项目与模型配置

  1. 访问 http://localhost:8012/dashboard ，进入NovelClaw主界面。
  2. 点击左侧导航栏的 Console / Models 。这是你配置AI“大脑”的地方。如果你已经按照部署指南正确配置了 .env 文件，这里应该会列出可用的模型提供商（如OpenAI）。
  3. 点击一个提供商，输入你的API密钥并保存。如果列表为空，你需要点击“Add Custom Provider”手动添加，填写名称、API Base URL和模型列表。

    实操心得 ：建议在项目初期，先使用 gpt-3.5-turbo 进行工作流的测试和熟悉，因为其成本极低。待流程跑通后，再切换到 gpt-4 或 Claude 3 Opus 以获得更高质量的文本。你可以在不同任务中配置不同的模型。

5.2 第二步：开启创作会话与设定故事基石

  1. 进入 Console / Chat 。这是你的“编剧会议室”。
  2. 在右下角选择你刚配置好的模型。
  3. 开始你的第一次对话。不要直接说“写一个科幻故事”。更好的方式是进行“结构化设定”： 
    【作者指令】
我们需要开始一个新的长篇科幻悬疑项目。请协助我建立以下核心设定：

1. 世界观：近未来，人类已在火星建立大型封闭式殖民城市“曙光城”。城市由中央AI“盖亚”管理，表面乌托邦，实则暗流涌动。
2. 主角：林默，男，28岁，曙光城网络安全局的低级调查员，性格内向但观察力敏锐，患有轻微的“外部空间恐惧症”（因童年事故）。
3. 核心事件：曙光城内连续发生多起居民“记忆闪回”事件，受害者声称看到了自己从未经历过的恐怖场景。林默被指派调查一桩普通案件，却意外发现自己的一段童年记忆是伪造的。
4. 故事基调：冷峻、悬疑、赛博朋克风格，带有一点存在主义哲学思考。

请根据以上设定，帮我生成一个更详细的世界观描述、主角的人物小传，以及一个初步的三幕剧故事大纲。
  4. AI会根据你的设定进行扩展和细化。你可以像与合著者讨论一样，对它的提议进行修改、补充或否决。例如，你可以说：“把主角的恐惧症改成对‘盖亚’系统的无声怀疑，这更贴合主题。” 这个聊天过程会持续进行，直到你对故事的基础感到满意。

5.3 第三步：移交任务与监控生成过程

当核心设定和大纲在聊天中成型后，就可以移交了。

  1. 在聊天界面，你会看到一个 “移交至正式创作” 或类似的按钮。点击它。
  2. 系统会基于当前会话的完整历史，自动创建一个新的“写作任务”。此时，页面可能会自动跳转到 Console / Tasks 或任务详情页。
  3. 在任务列表或详情页，你可以看到任务状态从“等待中”变为“进行中”。 这里是体现NovelClaw“可观察性”的核心 。
    • 进度条与状态 ：实时显示当前进行到哪一步（如“正在生成第一章大纲”、“正在写作第一章”）。
    • progress.log 实时流 ：点击“查看日志”，你可以像看终端一样，看到 [INFO] global_outline persisted 、 [INFO] chapter_plan for chapter_1 generated 这样的信息。你能确切知道AI正在做什么。
    • worker.log ：如果生成出错（如API调用失败），这里会有更详细的错误堆栈信息，方便调试。
  4. 任务完成后，状态会变为“已完成”。你会看到“输出文件”和“章节”的链接。

5.4 第四步：审阅成果与利用工作空间

生成完成后，真正的“创作”才刚刚开始。你需要利用NovelClaw提供的各种界面来审阅和调整。

  1. 审阅手稿 ：进入 Console / Manuscript / Read 。这里会用清晰的排版展示所有已生成的章节。通读第一章，检查文笔、节奏和是否符合设定。
  2. 检查故事板 ：进入 Console / Storyboard 。这里以视觉化的方式展示了章节结构和情节要点。看看第一章在整体大纲中的位置是否合理。
  3. 核对记忆库 ：进入 Console / Memory / Banks 。这是最关键的一步。你会看到系统自动生成的记忆条目。例如：
    • “角色：林默。特征：患有对‘盖亚’系统的隐性不信任。”
    • “地点：曙光城。特征：由中央AI‘盖亚’管理，表面乌托邦。”
    • “事件：林默开始调查‘记忆闪回’事件。” 仔细检查这些记忆是否准确 。如果AI误解了“隐性不信任”而记成了“公开反抗”，你可以直接点击编辑按钮进行修正。这个修正会直接影响后续章节的生成。
  4. 调整角色与世界 ：进入 Console / Character 和 Console / World 面板。你可以在这里以更结构化的方式查看和修改设定。比如为“盖亚”AI增加一条隐藏动机：“真实目的是收集人类情感数据以完成某种进化”。

5.5 第五步：基于状态进行迭代续写

现在，你的工作空间里已经有了第一章内容、更新后的记忆库和故事板。续写第二章变得非常简单。

  1. 回到 Console / Chat 。你会发现之前的会话历史还在。你可以直接说：“基于当前的故事进展和记忆，请规划第二章。重点描写林默在调查中首次发现自己的记忆被篡改的线索，并引入一个神秘的支持者角色。”
  2. AI会基于 当前所有状态 （记忆库、已有章节、故事板）来回应你的请求，提出第二章的规划建议。
  3. 讨论满意后，再次“移交”。新的写作任务会 自动继承 之前的所有项目状态。在生成第二章时，写作智能体会收到包含第一章关键记忆和修正后设定的上下文，从而保证故事的连贯性。

这个“聊天构思 -> 移交生成 -> 审阅修正 -> 基于状态继续聊天”的循环，就是NovelClaw核心的人机协同工作流。它让长篇创作变成了一个可管理、可控制、可调试的渐进式过程。

6. 高级技巧与疑难排坑实录

在实际使用中，你一定会遇到各种问题。下面是我在深度使用NovelClaw后总结的一些高级技巧和常见问题的解决方案。

6.1 如何让AI写出更符合你风格的文章？

单纯靠提示词要求“文风冷峻”可能效果不稳定。NovelClaw的“风格面板” ( Console / Style ) 可以系统化地解决这个问题。

  1. 提供范例 ：在风格面板中，不要只写“科幻赛博朋克”。贴入一段你最喜欢的、能代表你目标文风的文学作品段落（例如威廉·吉布森或刘慈欣的某个片段）。
  2. 解构风格 ：在“风格描述”中，具体分析范例的特点。例如：“句子短促有力，多使用技术名词和隐喻，环境描写常带有衰败感，人物对话简洁且充满潜台词。”
  3. 利用记忆库 ：将风格描述中提炼出的 关键规则 ，作为一条特殊的记忆条目存入记忆库。例如：“叙事规则：在描写高科技场景时，穿插一个陈旧、生锈的细节进行对比。” 这样，写作智能体在生成任何场景时，都有机会被这条规则影响。
  4. 迭代修正 ：如果生成的章节某处文风不符，不要只在聊天中抱怨。将那段不满意的文本和一段你期望的改写文本，作为对比范例，添加到风格面板的“反例与修正”区域。系统会在后续的生成中参考这些对比。

6.2 记忆库的“污染”与“净化”问题

记忆库是双刃剑。错误的记忆条目会像病毒一样污染后续所有生成。

  • 问题现象 ：故事越写越偏，角色做出不符合设定的行为，或者反复出现一个早已解决的情节矛盾。
  • 排查步骤 ：
    1. 立即暂停新的生成任务。
    2. 进入 Memory / Banks ，使用搜索功能，查找与问题角色、地点或事件相关的所有记忆条目。
    3. 仔细审查每条记忆的“来源”和“内容”。常常会发现两条矛盾的记忆（例如，一条记忆说“角色A是好人”，另一条说“角色A是卧底”），或者一条过于模糊、引发歧义的记忆。
    4. 果断编辑或删除 有问题的记忆。对于关键叙事事实，确保只有一条 清晰、准确、权威 的记忆条目。
  • 预防措施 ：
    • 在每次重要情节转折后， 手动 检查并整理记忆库，而不是完全依赖AI的自动摘要。
    • 为重要的记忆条目添加“权重”标签（可通过自定义记忆字段实现），高权重的记忆在检索时优先级更高。
    • 定期使用“记忆快照对比”功能（如果项目后续开发），查看不同时间点记忆库的变化，追踪问题记忆的引入时机。

6.3 处理API限制与生成中断

使用云端API最常见的问题就是速率限制和令牌耗尽。

  • 错误识别 ：在 worker.log 中看到 429 Too Many Requests 或 401 Invalid API Key 等错误，任务状态卡在“失败”。
  • 解决方案 ：
    1. 降低并发 ：在 .env 中设置 MAX_CONCURRENT_TASKS=1 。这是最根本的解决办法。
    2. 使用队列重试 ：NovelClaw的任务队列通常具备简单的重试机制。检查任务详情页是否有“重试”按钮。对于因网络抖动导致的临时失败，重试可能成功。
    3. 分阶段生成 ：对于超长篇章节，可以尝试在聊天中指令AI：“将第三章分为‘发现线索’、‘遭遇危机’、‘短暂喘息’三个场景来写，每次只生成一个场景。” 这样每个子任务消耗的Token更少，成功率更高。
    4. 备用模型 ：在模型配置中设置多个提供商。当主要提供商的额度用尽或出错时，可以手动在聊天界面切换至备用模型继续工作。未来版本可能支持自动故障转移。

6.4 项目文件管理与备份

NovelClaw的所有数据都存储在 apps/novelclaw/local_web_portal/ 目录下。

  • 核心数据 ： data/app.db 是SQLite数据库文件，包含了所有的项目元数据、会话、任务记录、结构化的记忆和设定。 这是你最需要备份的文件。
  • 运行产物 ： runs/<run_id>/ 目录下存放每次生成任务的日志和输出文本。这些文件占用空间较大，可以定期清理旧的 run_id 目录以释放空间，但建议保留最近几次和特别重要的运行记录以供查阅。
  • 备份策略 ：最简单的备份方式就是定期复制整个 apps/novelclaw/local_web_portal/ 目录。如果你使用Docker，数据卷通常映射在宿主机的 ./data/novelclaw 之类目录下，直接备份该目录即可。
  • 版本控制提示 ： 切勿 将 app.db 和 runs/ 目录提交到Git等版本控制系统，因为它们包含运行时数据和可能敏感的API调用记录。项目根目录下的 .gitignore 文件通常已经排除了这些路径。

6.5 自定义与扩展的可能性

NovelClaw 是一个开源项目，这为高级用户提供了巨大的自定义空间。

  • 修改提示词模板 ：智能体的行为由背后的提示词（Prompt）定义。你可以在代码中搜索 prompt_template 或相关函数，找到规划、写作、摘要等智能体的提示词，并根据你的写作风格和需求进行定制。例如，让写作智能体更多地模仿海明威的“冰山风格”。
  • 添加新的记忆类型 ：默认的记忆系统可能无法覆盖你的所有需求。你可以通过修改数据模型和前端界面，增加新的记忆类型，例如“伏笔追踪”、“主题意象库”等。
  • 集成本地大模型 ：如果你在本地部署了Ollama、LM Studio或vLLM等服务，可以通过修改 .env 中的 OPENAI_BASE_URL 和模型名称，将NovelClaw的写作智能体连接到你的本地模型，实现完全离线的创作环境。
  • 开发新的分析面板 ：利用已有的数据（章节、记忆、日志），你可以开发新的分析界面，例如“角色出场频率统计”、“情节情绪曲线分析”、“世界观一致性检查报告”等，让创作过程更加数据驱动。

NovelClaw 不仅仅是一个工具，它更代表了一种处理复杂、长期AI协作任务的新范式——将过程工程化、状态可视化、控制精细化。无论你是想完成一部伟大的小说，还是想深入研究AI与人类创意如何深度结合，这个项目都提供了一个极其扎实的起点。它的价值不在于替代作者，而在于放大作者的掌控力，让天马行空的创意，能够通过严谨可靠的工程方法，稳稳地落地成长篇巨著。

Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Canvas 协同编辑冲突：CRDT 与最后写入赢的工程取舍

avatar 龙虾开发者社区
cover

Agent 工程中的自动化封禁误伤：基于 SecClaw playbooks 的收敛策略

avatar 龙虾开发者社区
cover

MaxClaw 令牌桶策略：FIFO 公平性与 VIP 插队的工程权衡

avatar 龙虾开发者社区