快速开始

安装

npm i -g @actalk/inkos

通过 OpenClaw 使用 🦞

InkOS 已发布为 OpenClaw Skill，可被任何兼容 Agent（Claude Code、OpenClaw 等）直接调用：

clawhub install inkos          # 从 ClawHub 安装 InkOS Skill

通过 npm 安装或克隆本项目时，skills/SKILL.md 已包含在内，🦞 可直接读取——无需额外从 ClawHub 安装。

安装后，Claw 应优先通过共享交互入口调用 InkOS：

inkos interact --json --message "继续当前书，但把节奏再收紧一点"

这条入口直接走和项目 TUI 相同的交互执行内核，因此 OpenClaw、TUI、Studio 共用同一套控制脑。当前 JSON 输出包含 assistant 文本回复和 interaction session 信息；真正的执行结果以工具结果和落盘文件为准，不从模型口头声明推断完成。

plan chapter / compose chapter / draft / audit / revise / write next 这些原子命令仍然保留，但更适合作为底层工具，而不是 OpenClaw 的首选入口。也可以在 ClawHub 搜索 inkos 在线查看。

启动开放世界 / 分支互动

在 Studio Chat 里选择「开放世界」或「分支互动」，直接用自然语言描述你想玩的世界：

做一个魔兽风格的边境哨塔开放世界。时间不是固定回合，巡逻是一小时，练功可以跨几天。装备有稀有度，但不要数值面板，用材质和光泽体现。

系统会生成世界、角色、物品、证据、关系、当前场景和可选动作。开放世界支持自由输入动作；分支互动会给出可点击选项。配置封面 / 图片服务后，角色、物品、证据、场景都可以生成图，并在对话流里滚动显示。

---

控制面与运行时产物

除了运行时状态，InkOS 还把“护栏”和“自定义”拆成可审阅的控制层：

• story/author_intent.md：长期作者意图
• story/current_focus.md：当前阶段的关注点
• story/runtime/chapter-XXXX.intent.md：本章目标、保留项、避免项、冲突处理
• story/runtime/chapter-XXXX.context.json：本章实际选入的上下文
• story/runtime/chapter-XXXX.rule-stack.yaml：本章的优先级层和覆盖关系
• story/runtime/chapter-XXXX.trace.json：本章输入编译轨迹

这样 brief、卷纲、书级规则、当前任务不再混成一坨 prompt，而是先编译，再写作。

使用模式

InkOS 提供四种交互方式，底层共享同一组原子操作：

Studio 实测截图与生成结果

<p align="center"> <img src="assets/studio-dashboard.png" width="760" alt="InkOS Studio 开始创作入口"> </p>

<p align="center"> <strong>InkOS Short 手机封面</strong><br> <img src="assets/inkos-short-demo-cover.png" width="260" alt="短篇封面"> </p>

<p align="center"> <strong>InkOS Play 恋爱互动</strong><br> <img src="assets/play-openworld-romance.png" width="560" alt="恋爱互动"> </p>

<p align="center"> <strong>InkOS Play 侦探互动</strong><br> <img src="assets/play-openworld-detective.png" width="560" alt="侦探互动"> </p>

<p align="center"> <strong>InkOS Play 物品配图</strong><br> <img src="assets/play-item-warcraft.png" width="560" alt="物品配图"> </p>

第一张是当前 Studio 的本地实测截图。后面四张来自 InkOS Short 和 InkOS Play 的真实本地生成结果：短篇封面用于手机端缩略图点击，Play 图用于展示开放世界、侦探证据、互动场景和物品视觉能力。

配置

当前 InkOS 将 LLM 配置分成两条清晰路径：Studio 用可视化服务配置，CLI / daemon / 部署环境支持 env 覆盖。两者不会互相污染。

方式一：Studio 服务配置（推荐）

适合本地写作、Web 工作台和可视化管理。

inkos init my-novel
cd my-novel
inkos

打开 Studio 后进入「模型配置」：

1. 选择服务商，例如 Google Gemini、Moonshot、MiniMax、智谱、百炼或自定义端点。
2. 粘贴 API Key，点击「测试连接」。
3. 选择可用模型，保存配置。
4. 回到书籍页面开始写作。

Studio 运行时只使用：

provider bank 默认值
→ inkos.json 里的 services / 当前 service / defaultModel
→ .inkos/secrets.json 里的 service API Key

即使检测到 ~/.inkos/.env 或项目 .env，Studio 也只会展示提示，不会用 env 覆盖 service、model、baseUrl 或 API Key。API Key 存在项目内的 .inkos/secrets.json，不会写进 inkos.json。

方式二：CLI / daemon / 部署环境的 env 配置

适合终端批处理、服务器部署、CI、Docker、守护进程和一次性切模型。

全局 env：

inkos config set-global \
  --provider <openai|anthropic|custom> \
  --base-url <API 地址> \
  --api-key <你的 API Key> \
  --model <模型名>

也可以手动写 ~/.inkos/.env 或项目 .env：

```bash INKOS_LLM_PROVIDER=custom INKOS_LLM_BASE_URL=https://api.moonshot.cn/v1 INKOS_LLM_API_KEY=sk-... INKOS_LLM_MODEL=kimi-k2.5

LLM 配置更新

• Studio / CLI 配置隔离：Studio 固定使用服务页配置和 .inkos/secrets.json；CLI、daemon、部署环境支持 env 覆盖和一次性命令参数。
• Provider bank 能力表：内置 Google Gemini、Moonshot、MiniMax、智谱、百炼、DeepSeek、硅基流动、火山、腾讯混元、文心、讯飞星火、OpenRouter、kkaiapi、Ollama、CodingPlan 等服务的 baseUrl、协议、模型和兼容策略。
• 模型归属校验：--service google --model kimi-k2.5 这类错配会直接报错，避免把请求发到错误服务商。
• Google Gemini 兼容修复：AI Studio API Key 可直接用于 Gemini OpenAI-compatible endpoint，InkOS 会自动禁用 Google 不支持的 OpenAI store 参数。
• MiniMax transport 探测：MiniMax / MiniMax CodingPlan 使用官方 OpenAI-compatible /v1 入口，并自动使用可工作的非流式 transport，规避流式 usage 正常但正文为空的问题。
• 旧 env 兼容：老的 INKOS_LLM_BASE_URL + INKOS_LLM_MODEL + INKOS_LLM_API_KEY 仍可用于 CLI；没有 INKOS_LLM_SERVICE 时会尝试从 baseUrl 反推服务商。

给不同 agent 配不同模型/提供商

inkos config set-model writer <model> --provider <provider> --base-url <url> --api-key-env <ENV_VAR> inkos config set-model auditor <model> --provider <provider> inkos config show-models # 查看当前路由

未单独配置的 Agent 自动使用全局模型。

#### 配置排查

doctor 会显示当前 effective config mode、service/model/API Key 来源，并尝试 API 连通性。常见模式：

如果服务测试失败，优先检查服务商、模型和协议是否匹配。Google Gemini 的 AI Studio API Key 可用于 Gemini OpenAI-compatible endpoint；InkOS 会自动禁用 Google 不支持的 OpenAI store 参数。MiniMax / MiniMax CodingPlan 默认走官方 OpenAI-compatible /v1/chat/completions，并优先使用可工作的非流式 transport，避免流式返回 usage 但无正文的问题。

多模型路由

不同 Agent 可以走不同模型和 Provider。写手用 Claude（创意强），审计用 GPT-4o（便宜快速），雷达用本地模型（零成本）。inkos config set-model 按 agent 粒度配置，未配置的自动回退全局模型。

本地模型兼容

支持任何 OpenAI 兼容接口（Studio 里新增自定义服务，或 CLI 使用 --provider custom / INKOS_LLM_PROVIDER=custom）。服务测试会尝试不同协议和流式开关组合，并保存或提示可用 transport。Fallback 解析器处理小模型不规范输出，流中断时自动恢复部分内容。