Imported from zxerai/novelix (
skills/SKILL.md). Install upstream withnpx skills add zxerai/novelix --skill skills. Copyright stays with the author.
JiaOS - Autonomous Novel Writing Agent
JiaOS is a CLI tool for autonomous fiction writing powered by LLM agents. It orchestrates a multi-agent pipeline (Radar → Planner → Composer → Architect → Writer → Observer → Reflector → Normalizer → Auditor → Reviser) to generate, audit, and revise novel content with zero human intervention per chapter.
The pipeline operates in three phases:
- Phase 1 (Creative Writing, temp 0.7): Planner generates chapter intent with hook agenda, Composer selects relevant context, Writer produces prose with length governance, first-screen hooks, semantic density, hook-ledger payoff, and mobile paragraph rhythm guidance.
- Phase 2 (State Settlement, temp 0.3): Observer over-extracts 9 categories of facts, Reflector outputs a JSON delta (not full markdown), code-layer applies Zod schema validation and immutable state update. Hook operations use upsert/mention/resolve/defer semantics.
- Phase 3 (Quality Loop): Normalizer adjusts chapter length, Auditor runs 33-dimension check including hook health analysis, Reviser auto-fixes critical issues. Self-correction loop runs until all critical issues clear.
Truth files are persisted as schema-validated JSON (story/state/*.json) with markdown projections for human readability. SQLite temporal memory database (story/memory.db) enables relevance-based retrieval on Node 22+.
When to Use JiaOS
- English novel writing: Native English support with 10 genre profiles (LitRPG, Progression Fantasy, Isekai, etc.). Set
--lang en - Chinese web novel writing: 5 built-in Chinese genres (xuanhuan, xianxia, urban, horror, other)
- Fan fiction: Create fanfic from source material with 4 modes (canon, au, ooc, cp)
- Batch chapter generation: Generate multiple chapters with consistent quality
- Import & continue: Import existing chapters from a text file, reverse-engineer truth files, and continue writing
- Style imitation: Analyze and adopt writing styles from reference texts
- Spinoff writing: Write prequels/sequels/spinoffs while maintaining parent canon
- Standalone short fiction: Generate a complete short-fiction package with outline, draft, review artifacts, synopsis, selling points, and optional cover image
- Cover generation: Generate or regenerate only a cover prompt and cover image from a title, synopsis, or visual direction without rerunning story writing
- Quality auditing: Detect AI-generated content and perform 33-dimension quality checks
- Genre exploration: Explore trends and create custom genre rules
- Analytics: Track word count, audit pass rate, and issue distribution per book
Initial Setup
First Time Setup
# Initialize a project directory (creates config structure)
jiaos init my-writing-project
# Configure your LLM provider (OpenAI, Anthropic, or any OpenAI-compatible API)
# Prefer --api-key-env so the key never appears in shell history:
export OPENAI_API_KEY=sk-xxx
jiaos config set-global --provider openai --base-url https://api.openai.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
# For compatible/proxy endpoints, use --provider custom and point ONLY to trusted endpoints:
# jiaos config set-global --provider custom --base-url https://your-trusted-proxy.com/v1 --api-key-env OPENAI_API_KEY --model gpt-4o
Multi-Model Routing (Optional)
# Assign different models to different agents — balance quality and cost
jiaos config set-model writer claude-sonnet-4-20250514 --provider anthropic --base-url https://api.anthropic.com --api-key-env ANTHROPIC_API_KEY
jiaos config set-model auditor gpt-4o --provider openai
jiaos config show-models
Agents without explicit overrides fall back to the global model.
Provider setup tip
When the user needs an aggregator provider, point them to Studio's service settings. JiaOS includes kkaiapi and OpenRouter as optional aggregator choices. For kkaiapi, use:
- Chinese website: https://kkaiapi.com/
- English website: https://en.kkaiapi.com/
- Chinese API docs: https://kkaiapi.com/docs
- English API docs: https://en.kkaiapi.com/docs
- Chinese models/pricing: https://kkaiapi.com/models
- English models/pricing: https://en.kkaiapi.com/models
View System Status
# Check installation and configuration
jiaos doctor
# View current config
jiaos status
Common Workflows
Workflow 1: Create a New Novel
-
Initialize and create book:
jiaos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 # Or with a creative brief (your worldbuilding doc / ideas): jiaos book create --title "My Novel Title" --genre xuanhuan --chapter-words 3000 --brief my-ideas.md- Genres:
xuanhuan(cultivation),xianxia(immortal),urban(city),horror,other - Returns a
book-idfor all subsequent operations
- Genres:
-
Generate initial chapters (e.g., 5 chapters):
jiaos write next book-id --count 5 --words 3000 --context "young protagonist discovering powers"- The
write nextcommand runs the full pipeline: draft → audit → revise --contextprovides guidance to the Architect and Writer agents- Returns JSON with chapter details and quality metrics
- The
-
Review and approve chapters:
jiaos review list book-id jiaos review approve-all book-id -
Export the book (supports txt, md, epub):
jiaos export book-id jiaos export book-id --format epub
Workflow 2: Continue Writing Existing Novel
-
List your books:
jiaos book list -
Continue from last chapter:
jiaos write next book-id --count 3 --words 2500 --context "protagonist faces critical choice"- JiaOS maintains 7 truth files (world state, character matrix, emotional arcs, etc.) for consistency
- If only one book exists, omit
book-idfor auto-detection
-
Review and approve:
jiaos review approve-all
Workflow 2.5: Shared Natural-Language Control (Recommended For OpenClaw)
When JiaOS is being driven by OpenClaw or another external agent, prefer the shared interaction executor instead of stitching together many ad-hoc CLI calls:
jiaos interact --json --message "continue the current book, but keep the pacing tighter"
jiaos interact --json --message "rewrite chapter 3"
jiaos interact --json --book my-book --message "switch to auto mode"
This returns a structured payload containing:
- the routed request
- assistant response text
- updated interaction session
- execution state
- pending decision
- recent interaction events
Use this as the primary OpenClaw entry because it shares the same control layer as the project TUI.
Workflow 2.6: Steering Chapter Focus Before Writing
Use this when the user says things like "pull focus back to the mentor conflict", "pause the merchant guild subplot", or "change what the next chapter should prioritize".
-
Update the book-level control docs when needed:
- Use
update_author_intentto change the long-horizon identity of the book - Use
update_current_focusto change the next 1-3 chapters' focus
- Use
-
Compile the next chapter intent:
plan_chapter(bookId, guidance?)- Generates
story/runtime/chapter-XXXX.intent.md - Use this to verify what the system thinks the next chapter should do
- Generates
-
Compose the actual runtime input package:
compose_chapter(bookId, guidance?)- Generates
story/runtime/chapter-XXXX.context.json - Generates
story/runtime/chapter-XXXX.rule-stack.yaml - Generates
story/runtime/chapter-XXXX.trace.json
- Generates
-
Only then write:
write_draftif the user wants intermediate reviewwrite_full_pipelineif they want the usual write → audit → revise flow
Recommended orchestration:
- user asks to redirect focus
update_current_focusplan_chaptercompose_chapter- inspect the resulting intent/paths
write_draftorwrite_full_pipeline
Workflow 3: Import Existing Chapters & Continue
Use this when you have an existing novel (or partial novel) and want JiaOS to pick up where it left off.
-
Import from a single text file (auto-splits by chapter headings):
jiaos import chapters book-id --from novel.txt- Automatically splits by
第X章pattern - Custom split pattern:
--split "Chapter\\s+\\d+"
- Automatically splits by
-
Import from a directory of separate chapter files:
jiaos import chapters book-id --from ./chapters/- Reads
.mdand.txtfiles in sorted order
- Reads
-
Resume interrupted import:
jiaos import chapters book-id --from novel.txt --resume-from 15 -
Continue writing from the imported chapters:
jiaos write next book-id --count 3- JiaOS reverse-engineers all 7 truth files from the imported chapters
- Generates a style guide from the existing text
- New chapters maintain consistency with imported content
Workflow 4: Style Imitation
-
Analyze reference text:
jiaos style analyze reference_text.txt- Examines vocabulary, sentence structure, tone, pacing
-
Import style to your book:
jiaos style import reference_text.txt book-id --name "Author Name"- All future chapters adopt this style profile
- Style rules become part of the Reviser's audit criteria
Workflow 5: Spinoff/Prequel Writing
-
Import parent canon:
jiaos import canon spinoff-book-id --from parent-book-id- Creates links to parent book's world state, characters, and events
- Reviser enforces canon consistency
-
Continue spinoff:
jiaos write next spinoff-book-id --count 3 --context "alternate timeline after Chapter 20"
Workflow 6: Fine-Grained Control (Draft → Audit → Revise)
If you need separate control over each pipeline stage:
-
Generate draft only:
jiaos draft book-id --words 3000 --context "protagonist escapes" --json -
Audit the chapter (33-dimension quality check):
jiaos audit book-id chapter-1 --json- Returns metrics across 33 dimensions including pacing, dialogue, world-building, outline adherence, and more
-
Revise with specific mode:
jiaos revise book-id chapter-1 --mode polish --json- Modes:
polish(minor),spot-fix(targeted),rewrite(major),rework(structure),anti-detect(reduce AI traces)
- Modes:
Workflow 7: Monitor Platform Trends
jiaos radar scan
- Analyzes trending genres, tropes, and reader preferences
- Informs Architect recommendations for new books
Workflow 8: Detect AI-Generated Content
# Detect AIGC in a specific chapter
jiaos detect book-id
# Deep scan all chapters
jiaos detect book-id --all
- Uses 11 deterministic rules (zero LLM cost) + optional LLM validation
- Returns detection confidence and problematic passages
Workflow 9: View Analytics
jiaos analytics book-id --json
# Shorthand alias
jiaos stats book-id --json
- Total chapters, word count, average words per chapter
- Audit pass rate and top issue categories
- Chapters with most issues, status distribution
- Token usage stats: total prompt/completion tokens, avg tokens per chapter, recent trend
Workflow 10: Write an English Novel
# Create an English LitRPG novel (language auto-detected from genre)
jiaos book create --title "The Last Delver" --genre litrpg --chapter-words 3000
# Or set language explicitly
jiaos book create --title "My Novel" --genre other --lang en
# Set English as default for all projects
jiaos config set-global --lang en
- 10 English genres: litrpg, progression, isekai, cultivation, system-apocalypse, dungeon-core, romantasy, sci-fi, tower-climber, cozy
- Each genre has dedicated pacing rules, fatigue word lists (e.g., "delve", "tapestry", "testament"), and audit dimensions
- Use
jiaos genre listto see all available genres
Workflow 11: Fan Fiction
# Create a fanfic from source material
jiaos fanfic init --title "My Fanfic" --from source-novel.txt --mode canon
# Modes: canon (faithful), au (alternate universe), ooc (out of character), cp (ship-focused)
jiaos fanfic init --title "What If" --from source.txt --mode au --genre other
- Imports and analyzes source material automatically
- Fanfic-specific audit dimensions and information boundary controls
- Ensures new content stays consistent with source canon (or deliberately diverges in au/ooc modes)
Workflow 12: Rename Characters or Entities Across Entire Book
# Via interact
jiaos interact --json --message "把林烬改成张三"
jiaos interact --json --message "rename Lin Jin to Zhang San"
# Via slash command
jiaos interact --json --message "/rename 林烬 => 张三"
- Scans all chapters + all truth files (story_bible, current_state, character_matrix, etc.)
- Replaces every occurrence in one pass
- Returns count of files touched
Workflow 13: Patch Specific Text in a Chapter
jiaos interact --json --message "/replace 5 旧文本 => 新文本"
- Precisely replaces text in chapter 5 only
- Marks chapter for review after patching
Workflow 14: Interactive TUI Dashboard
jiaos
- Launches a full-screen Ink + React dashboard with conversational creation
- Slash command autocomplete (Tab), input history (arrow keys)
- Themed activity animations per operation (writing, auditing, revising, planning)
- Bilingual i18n (Chinese / English)
- Shares the same interaction kernel as
jiaos interactand Studio
Workflow 15: Standalone Short Fiction Package
Use this when the user wants a complete short story or short-fiction deliverable that is separate from the active long-form book.
jiaos short run \
--direction "modern short fiction marriage reversal evidence-driven heroine" \
--chapters 12 \
--chars 1000
Outputs are written under shorts/<story-name>/final/:
full.md— complete short-fiction manuscriptsales-package.md— synopsis and selling pointscover-prompt.md— cover promptcover.png— cover image when a cover provider is configured
For OpenClaw/Studio/agent orchestration, call the short_fiction_run tool when the user asks for a new complete short-fiction package. Do not use it for the next chapter of an existing long-form book.
Workflow 16: Standalone Cover Tool
Use this when the user only wants a cover for an existing title, synopsis, or visual direction. Do not rerun the short-fiction pipeline.
In Studio or agent mode, ask naturally:
Generate a short-fiction cover for "The Divorce Papers He Regretted", modern city, high-drama reversal.
For tool-using agents, call generate_cover with:
title— requiredintroorsellingPoints— optional story contextcoverPrompt— optional visual directionoutputDir— optional; defaults tocovers/<title>/
The standalone cover tool writes:
covers/<title>/cover-prompt.mdcovers/<title>/cover.png
If cover image generation fails, report the provider/configuration error plainly. Do not rewrite the story, do not rerun short_fiction_run, and do not suggest unrelated external tools unless the user asks.
JiaOS Studio (Web Workbench)
jiaos studio launches a local web UI (default port 4567) that provides a visual interface for all JiaOS operations:
- Book management — create, delete, export (TXT/MD/EPUB), configure per-book settings
- Short fiction & cover tools — generate independent short-fiction packages, synopsis/selling points, cover prompts, and standalone covers
- Chapter review & editing — approve/reject drafts, edit content inline, multi-mode revision (polish/spot-fix/rewrite/anti-detect)
- Real-time writing progress — SSE-based live updates during chapter generation
- Market radar — AI-powered trend analysis with platform/genre recommendations
- Analytics — word count, audit pass rate, chapter ranking, token usage
- AI detection — scan chapters for AI-generated content
- Style analysis — analyze reference texts and import writing styles
- Genre management — create/customize genre profiles with fatigue words, pacing rules, audit dimensions
- Daemon control — start/stop background writing with event log
- Truth file editor — view and edit canonical knowledge base per book
- Config editor — LLM provider, model routing, notifications
jiaos studio # Start on default port 4567
jiaos studio -p 8080 # Start on custom port
The right-side AI Assistant panel in Studio shares the same interaction kernel as TUI and jiaos interact. You can type natural language commands (rename entities, write chapters, audit, export) directly in the assistant panel.
Advanced: Natural Language Agent Mode
For flexible, conversational requests:
jiaos agent "写一部都市题材的小说,主角是一个年轻律师,第一章三千字"
- Agent interprets natural language and invokes appropriate commands
- Useful for complex multi-step requests
Input Governance Tools
These tools are the preferred control surface for chapter steering:
-
plan_chapter(bookId, guidance?)- Generates chapter intent for the next chapter
- Use before writing when the user wants to change focus
-
compose_chapter(bookId, guidance?)- Generates runtime context/rule-stack/trace artifacts
- Use after planning and before writing
-
update_author_intent(bookId, content)- Rewrites
story/author_intent.md - Use for long-horizon changes to the book's identity
- Rewrites
-
update_current_focus(bookId, content)- Rewrites
story/current_focus.md - Use for local steering over the next 1-3 chapters
- Rewrites
Short Fiction and Cover Agent Tools
These are the preferred tools when JiaOS is driven by OpenClaw, Studio chat, or jiaos agent:
-
short_fiction_run- Creates an independent short-fiction package from a direction
- Runs outline → outline review/revision → full draft → draft review/revision → synopsis/selling points/cover prompt → optional cover image
- Writes to
shorts/<story-name>/ - Use only when the user asks for a separate complete short story / short-fiction deliverable
-
generate_cover- Generates only a cover prompt and cover image
- Writes to
covers/<title>/by default - Use when the user asks to create or regenerate a cover for an existing title, synopsis, or completed short
- Also use when the user changes the cover prompt through chat; pass the revised visual direction as
coverPromptand reuse the existingoutputDirwhen available - Do not rerun story generation unless the user explicitly asks for a new story
write_truth_file remains available for broad file edits, but prefer the dedicated control tools above for input-governance changes.
Key Concepts
Book ID Auto-Detection
If your project contains only one book, most commands accept book-id as optional. You can omit it for brevity:
# Explicit
jiaos write next book-123 --count 1
# Auto-detected (if only one book exists)
jiaos write next --count 1
--json Flag
All content-generating commands support --json for structured output. Essential for programmatic use:
jiaos draft book-id --words 3000 --context "guidance" --json
Truth Files (Long-Term Memory)
JiaOS maintains 7 files per book for coherence:
- World State: Maps, locations, technology levels, magic systems
- Character Matrix: Names, relationships, arcs, motivations
- Resource Ledger: In-world items, money, power levels
- Chapter Summaries: Events, progression, foreshadowing
- Subplot Board: Active and dormant subplots, hooks
- Emotional Arcs: Character emotional progression
- Pending Hooks: Unresolved cliffhangers and promises to reader
All agents reference these to maintain long-term consistency. Since 0.6.0, truth files are backed by schema-validated JSON in story/state/ with automatic bootstrap from markdown for legacy books. During import chapters, these files are reverse-engineered from existing content via the ChapterAnalyzerAgent.
Multi-Phase Writer Architecture
The Writer operates across multiple phases with specialized agents:
- Planner: Generates chapter intent with structured hook agenda (mustAdvance, eligibleResolve, staleDebt) based on memory retrieval.
- Composer: Selects relevant context from truth files by relevance scoring, compiles rule stack and runtime artifacts.
- Phase 1 (Creative, temp 0.7): Generates prose with length governance, English variance brief (anti-repetition), and dialogue-driven guidance.
- Phase 2a (Observer, temp 0.5): Over-extracts 9 categories of facts from the chapter text.
- Phase 2b (Reflector, temp 0.3): Outputs a JSON delta with hookOps (upsert/mention/resolve/defer), currentStatePatch, and chapterSummary. Code-layer validates via Zod schema and applies immutably.
- Normalizer: Single-pass compress/expand to bring chapter length into the target band. Safety net rejects destructive normalization (>75% content loss).
- Auditor: 33-dimension check including hook health analysis (stale debt, burst detection, no-advance warnings).
- Reviser: Auto-fixes critical issues, self-correction loop until clean.
Truth files use structured JSON (story/state/*.json) as the authoritative source, with markdown projections for human readability. Hook admission control prevents duplicate/family hooks from inflating the hook table.
Context Guidance
The --context parameter provides directional hints to the Writer and Architect:
jiaos write next book-id --count 2 --context "protagonist discovers betrayal, must decide whether to trust mentor"
- Context is optional but highly recommended for narrative coherence
- Supports both English and Chinese
Genre Management
View Built-In Genres
jiaos genre list
jiaos genre show xuanhuan
Create Custom Genre
jiaos genre create my-genre --name "My Genre"
# Options: --numerical, --power, --era
jiaos genre create dark-xuanhuan --name "Dark Xuanhuan" --numerical --power
Copy Built-in Genre for Customization
jiaos genre copy xuanhuan
# Copies to project genres/ directory for editing
Command Reference Summary
| Command | Purpose | Notes |
|---|---|---|
jiaos init [name] |
Initialize project | One-time setup |
jiaos book create |
Create new book | Returns book-id. --brief <file>, --lang en/zh, --genre litrpg/progression/... |
jiaos book list |
List all books | Shows IDs, statuses |
jiaos write next |
Full pipeline (draft→audit→revise) | Primary workflow command |
jiaos draft |
Generate draft only | No auditing/revision |
jiaos audit |
33-dimension quality check | Standalone evaluation |
jiaos revise |
Revise chapter | Modes: polish/spot-fix/rewrite/rework/anti-detect |
jiaos agent |
Natural language interface | Flexible requests |
jiaos style analyze |
Analyze reference text | Extracts style profile |
jiaos style import |
Apply style to book | Makes style permanent |
jiaos import canon |
Link spinoff to parent | For prequels/sequels |
jiaos import chapters |
Import existing chapters | Reverse-engineers truth files for continuation |
jiaos detect |
AIGC detection | Flags AI-generated passages |
jiaos export |
Export finished book | Formats: txt, md, epub |
jiaos analytics / jiaos stats |
View book statistics | Word count, audit rates, token usage |
jiaos radar scan |
Platform trend analysis | Informs new book ideas |
jiaos short run |
Generate standalone short fiction | Outputs manuscript, sales package, cover prompt, optional cover |
jiaos config set-global |
Configure LLM provider | OpenAI/Anthropic/custom (any OpenAI-compatible) |
jiaos config set-model <agent> <model> |
Set model override for a specific agent | --provider, --base-url, --api-key-env for multi-provider routing |
jiaos config show-models |
Show current model routing | View per-agent model assignments |
jiaos doctor |
Diagnose issues | Check installation |
jiaos update |
Update to latest version | Self-update |
jiaos up/down |
Daemon mode | Background processing. Logs to jiaos.log (JSON Lines). -q for quiet mode |
jiaos review list/approve-all |
Manage chapter approvals | Quality gate |
jiaos fanfic init |
Create fanfic from source material | --from <file>, --mode canon/au/ooc/cp |
jiaos genre list |
List all available genres | Shows English and Chinese genres with default language |
jiaos genre create <id> |
Create custom genre profile | --name, --numerical, --power, --era |
jiaos genre copy <id> |
Copy built-in genre to project | For customization |
jiaos write rewrite <book> <ch> |
Rewrite a specific chapter | Deletes chapter and later, rewrites from that point |
jiaos book update [book-id] |
Update book settings | --chapter-words, --target-chapters, --status, --lang |
jiaos book delete <book-id> |
Delete book and all chapters | --force to skip confirmation |
jiaos plan chapter [book-id] |
Generate chapter intent | Preview what next chapter will do before writing |
jiaos compose chapter [book-id] |
Generate runtime artifacts | Context, rule-stack, trace for next chapter |
jiaos consolidate [book-id] |
Consolidate chapter summaries | Reduces context for long books (volume-level summaries) |
jiaos eval [book-id] |
Quality evaluation report | --json, --chapters <range>. Composite quality score |
jiaos studio |
Start web workbench | -p for port. Local web UI for book management |
jiaos fanfic show [book-id] |
Display parsed fanfic canon | Shows imported source material analysis |
jiaos fanfic refresh [book-id] |
Re-import and regenerate fanfic canon | --from <file> for updated source material |
jiaos interact |
Shared interaction endpoint | --json, --message, --book. Primary entry for OpenClaw |
jiaos (no args) |
Launch TUI dashboard | Full-screen Ink + React interactive dashboard |
Error Handling
Common Issues
"book-id not found"
- Verify the ID with
jiaos book list - Ensure you're in the correct project directory
"Provider not configured"
- Run
jiaos config set-globalwith valid credentials - Check API key and base URL with
jiaos doctor
"Context invalid"
- Ensure
--contextis a string (wrap in quotes if multi-word) - Context can be in English or Chinese
"Audit failed"
- Check chapter for encoding issues
- Ensure chapter-words matches actual word count
- Try
jiaos revisewith--mode rewrite
"Book already has chapters" (import)
- Use
--resume-from <n>to append to existing chapters - Or delete existing chapters first
Running Daemon Mode
For long-running operations:
# Start background daemon
jiaos up
# Stop daemon
jiaos down
# Daemon auto-processes queued chapters
Tips for Best Results
- Provide rich context: The more guidance in
--context, the more coherent the narrative - Start with style: If imitating an author, run
jiaos style importbefore generation - Import first: For existing novels, use
jiaos import chaptersto bootstrap truth files before continuing - Review regularly: Use
jiaos reviewto catch issues early - Monitor audits: Check
jiaos auditmetrics to understand quality bottlenecks - Use spinoffs strategically: Import canon before writing prequels/sequels
- Batch generation: Generate multiple chapters together (better continuity)
- Check analytics: Use
jiaos analyticsto track quality trends over time - Export frequently: Keep backups with
jiaos export
Security & Trust
- License: the ClawHub skill descriptor is MIT-0 per platform policy, but the underlying
@actalk/jiaos,@actalk/jiaos-core, and@actalk/jiaos-studionpm packages are AGPL-3.0-only. Running JiaOS and distributing modified versions are governed by AGPL. Full source on GitHub for auditability. - No install hooks: npm package has no
preinstall/postinstall/installscripts. Install is inert. - Local-only file I/O: all read/write stays inside the project directory (
books/*,jiaos.json,jiaos.log). No writes outside the working directory. - No telemetry: JiaOS does not phone home, collect usage stats, or ship any data to JiaOS-controlled servers. The only outbound traffic is to the LLM provider endpoint you explicitly configure.
- Credential handling: always prefer
--api-key-env <VAR_NAME>over--api-key <literal>so keys never hit shell history. Keys are stored injiaos.jsonunder your project directory — treat it like a secret and add it to.gitignoreif you commit the project. - Custom provider base-URL:
--provider customforwards your API key to whatever URL you specify. Only point it at endpoints you trust (your own proxy or an audited reverse-proxy). Never paste an untrusted--base-url. - No elevated privileges: JiaOS requires no sudo, no global state mutation, no network listening port (Studio binds
localhost:4567only).
Support & Resources
- Homepage: https://github.com/zxerai/jiaos
- Configuration: Stored in project root after
jiaos init - Truth files: Located in
books/<id>/story/per book, with structured JSON instory/state/ - Logs: Check output of
jiaos doctorfor troubleshooting
