7.20 ainovel-cli 使用说明

对话笔记直发：7.20 ainovel-cli 使用说明。分类：AI工程。

ainovel-cli 项目上手使用说明

一句话

这是一个「AI 全自动写小说」引擎，跑在我的云服务器 yun1 上（Docker 部署，OpenRouter 提供大模型）。本说明记录如何配置、启动、监控和导出小说。

---

一、它到底是什么

ainovel-cli 是一个确定性引擎 + 多智能体的小说写作工具：

• 你只给一句话设定（例如「写一本东方玄幻长篇，主角从边陲小城起步」）。
• 引擎自动规划大纲 → 分卷分章 → 逐章起草 → 自检一致性 → 审阅润色，全程无需手动干预。
• 三个智能体协作：Architect（规划）、Writer（写作）、Editor（审阅）。
• 自带断电/崩溃续写：进度落盘为 checkpoint，重跑自动接着写，不重复花钱。

我的部署方式

• 运行环境：云服务器 yun1（你的服务器IP（已脱敏），Ubuntu，Docker 29.1.3）
• 部署形态：Docker 容器 + headless（无界面后台）模式
• 大模型来源：OpenRouter（一个 key 能切Gemini/Claude/DeepSeek 等一堆模型）

---

二、服务器上的文件位置

路径	作用
/opt/ainovel/config/config.json	全局配置 + API Key（权限 600）
/opt/ainovel/config/	还可放 rules/、style/ 自定义规则与文风
/opt/ainovel/workspace/	小说成品与运行数据（落盘目录）
/opt/ainovel/workspace/output/	写出来的小说正文、大纲、meta
/opt/ainovel/start-novel.sh	启动脚本（改设定、一键开跑）
容器内 /root/.ainovel	上面 config 的挂载点
容器内 /workspace	上面 workspace 的挂载点
容器名	ainovel

---

三、配置文件长啥样

/opt/ainovel/config/config.json 当前内容：

{
  "provider": "openrouter",
  "model": "google/gemini-2.5-flash",
  "reasoning_effort": "medium",
  "providers": {
    "openrouter": {
      "api_key": "sk-or-v1-REPLACE_WITH_YOUR_KEY",
      "base_url": "https://openrouter.ai/api/v1",
      "models": [
        { "name": "google/gemini-2.5-flash", "context_window": 200000 }
      ]
    }
  },
  "style": "default"
}

字段说明：

• provider：用哪个服务商，对应 providers 里的 key。
• model：默认模型名（必须是 providers.<name>.models 里列出来的）。
• reasoning_effort：off / low / medium / high / xhigh / max，控制思考深度，越深越慢越贵。
• providers.openrouter.api_key：你的 OpenRouter Key（现在还是占位符，必须替换）。
• providers.openrouter.models[].context_window：上下文窗口大小，影响长文连贯性。

换模型要两处一起改

想换成 DeepSeek，要把 model 改成 "deepseek/deepseek-chat"，并在 models 数组里也加一条同名配置（带 context_window），否则会用不了。

---

四、上手四步（从零到开写）

第 1 步：拿 OpenRouter Key

去 https://openrouter.ai 注册，在 API Keys 页面创建一个 Key（格式 sk-or-v1-xxxx）。

第 2 步：把 Key 填进配置

在服务器上执行（把 你的真实Key 换成复制来的那串）：

ssh admin@`你的服务器IP（已脱敏）`
sudo sed -i 's#sk-or-v1-REPLACE_WITH_YOUR_KEY#你的真实Key#' /opt/ainovel/config/config.json

也可以直接 sudo vim /opt/ainovel/config/config.json 手动改。改完保存即生效，无需重启容器（下次运行生效）。

第 3 步：改小说设定（可选）

编辑启动脚本里的设定：

sudo vim /opt/ainovel/start-novel.sh
# 找到这一行改成你想要的主题：
# PROMPT="写一本东方玄幻长篇，主角从边陲小城起步，一步步登上巅峰"

第 4 步：开跑

bash /opt/ainovel/start-novel.sh

容器在后台启动，名字叫 ainovel，开始全自动写作。

---

五、日常怎么用

看写作进度

docker logs -f ainovel      # 实时滚动日志，Ctrl+C 退出查看，不影响写作

改小说题材 / 设定

改 /opt/ainovel/start-novel.sh 里的 PROMPT，然后重新跑脚本（见下）。

暂停 / 停止

docker stop ainovel        # 优雅停止，进度已落盘

断线、崩溃、续写（重点）

不管因为断网、停机还是手动 stop，只要再跑一次启动脚本，引擎会自动从 output/novel/meta/checkpoints.jsonl 接着写，不会重复消费 token：

bash /opt/ainovel/start-novel.sh

换大模型

编辑 config.json 的 model（及 models 列表），保存即可，下次运行生效。常用：

• google/gemini-2.5-flash（默认，便宜、上下文大）
• anthropic/claude-3.5-sonnet（质量高）
• deepseek/deepseek-chat（便宜、中文友好）

导出成书（TXT / EPUB）

docker exec -it ainovel ainovel-cli /export /workspace/output/novel.epub --overwrite
# 或导出 txt：
docker exec -it ainovel ainovel-cli /export /workspace/output/novel.txt --overwrite

产物在服务器 /opt/ainovel/workspace/output/，下载到本地即可。

加自己的写作规矩 / 文风

• 创作约束（人设不 OOC、禁某些套路等）：往 /opt/ainovel/config/rules/ 丢 .md 文件，用大白话写。
• 文风/语气：往 /opt/ainovel/config/style/ 放 voice.md、anti-ai-tone.md 等。
• 这些会按「本书配置 > 全局配置」合并生效。

升级版本

docker pull ghcr.io/voocel/ainovel-cli:latest
bash /opt/ainovel/start-novel.sh

---

六、命令速查表

想做啥	命令
启动写作	bash /opt/ainovel/start-novel.sh
看实时日志	docker logs -f ainovel
停掉任务	docker stop ainovel
看容器状态	docker ps -a | grep ainovel
进容器里操作	docker exec -it ainovel sh
导出 EPUB	docker exec -it ainovel ainovel-cli /export /workspace/output/novel.epub --overwrite
改 Key	sudo vim /opt/ainovel/config/config.json
改设定	sudo vim /opt/ainovel/start-novel.sh
升级镜像	docker pull ghcr.io/voocel/ainovel-cli:latest

---

七、注意事项

先短篇试跑，再开长篇

写一整本长篇会吃掉大量 token（也就是钱）。务必先用一个短篇设定试跑一遍，确认 Key 通了、文风满意，再开大长篇。

常见报错：HTTP 401 User not found

说明 OpenRouter Key 无效或还是占位符。回去第 2 步确认 config.json 里的 api_key 已换成真实 Key，且没有被换行/引号破坏。

不是 Web 服务，不占端口

ainovel 是后台批处理任务，不像网站那样有网址。想看稿子要么 docker logs 看过程，要么导出 EPUB/TXT 后下载。后续若想用浏览器看，可让 nginx 把 /opt/ainovel/workspace/output 只读暴露出来（暂未做）。

关于 "命令行不能传设定" 的误会

早期版本报错「不再支持命令行直接传入小说需求」，那是因为没加 --headless 被当成了交互模式。正确用法是 ainovel-cli --headless --prompt "..."，我的启动脚本已经写对了，直接用即可。

---

注：本文涉及的服务器公网 IP / Tailnet / 局域网 IP 已脱敏，请替换为你自己的地址。

---

相关： 00-索引-AI工程索引 7.25 在 yun1 部署 new-api 并通过 Cloudflare 域名 HTTPS 访问 — 实操记录