### Manual Docker Deployment Setup Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md Manually set up environment files and start services using Docker Compose. This method requires copying example .env files and editing them with your API keys before starting the containers. ```bash # 1. Setup environment files cp .env.auth-portal.example apps/auth-portal/.env cp .env.multiagent.example apps/multiagent/.env cp .env.novelclaw.example apps/novelclaw/.env # 2. Edit .env files with your API keys # 3. Start services docker-compose up -d ``` -------------------------------- ### Start Local Web Portal Wrapper Script Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/README.md Executes a PowerShell script to bootstrap the virtual environment, install dependencies, create the .env file if needed, and start the local web portal. ```powershell .\local_web_portal\start_local.ps1 ``` -------------------------------- ### Manual Local Environment Setup and Startup Source: https://github.com/ilearn-lab/novelclaw/blob/main/RUN_LOCAL_WEB.md These PowerShell scripts are used for manual setup of the local environment, including setting up environment variables, bootstrapping the shared virtual environment, and starting all local services. The `-RestartExisting` flag can be used to restart services if they are already running. ```powershell .\scripts\setup-local-env.ps1 -Overwrite ``` ```powershell .\scripts\bootstrap-shared-venv.ps1 ``` ```powershell .\scripts\start-all-local.ps1 -UseSharedVenv ``` ```powershell .\scripts\start-all-local.ps1 -UseSharedVenv -RestartExisting ``` -------------------------------- ### Install and Enable Systemd Service Units Source: https://github.com/ilearn-lab/novelclaw/blob/main/DEPLOYMENT.md Installs the systemd service files, reloads the systemd daemon, enables the services to start on boot, and restarts them. ```bash sudo cp infra/systemd/*.service /etc/systemd/system/ sudo systemctl daemon-reload sudo systemctl enable novelclaw-portal.service sudo systemctl enable novelclaw-multiagent.service sudo systemctl enable novelclaw.service sudo systemctl restart novelclaw-portal.service sudo systemctl restart novelclaw-multiagent.service sudo systemctl restart novelclaw.service ``` -------------------------------- ### Start NovelClaw with Docker (Windows) Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md Execute this batch script to start NovelClaw services using Docker on Windows. Ensure Docker is installed and running. ```batch .\docker-start.bat ``` -------------------------------- ### Create Python Virtual Environment and Install Dependencies Source: https://github.com/ilearn-lab/novelclaw/blob/main/DEPLOYMENT.md Sets up a Python virtual environment and installs project dependencies for all components. Ensure you are in the project's root directory before execution. ```bash cd /opt/novelclaw python3 -m venv .venv ./.venv/bin/pip install --upgrade pip setuptools wheel ./.venv/bin/pip install -r apps/auth-portal/requirements.txt ./.venv/bin/pip install -r apps/multiagent/requirements.txt ./.venv/bin/pip install -r apps/multiagent/local_web_portal/requirements.txt ./.venv/bin/pip install -r apps/novelclaw/requirements.txt ./.venv/bin/pip install -r apps/novelclaw/local_web_portal/requirements.txt ``` -------------------------------- ### Start Server Deployment Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/multiagent/local_web_portal/README.md Starts the web server for server deployment with multiple workers. It's recommended to use HTTPS and a reverse proxy like Nginx or Caddy for production. ```bash uvicorn local_web_portal.app.main:app --host 0.0.0.0 --port 8010 --workers 2 ``` -------------------------------- ### Start NovelClaw with Docker (Linux/Mac) Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md Make the shell script executable and run it to start NovelClaw services using Docker on Linux or macOS. Docker must be installed and running. ```bash chmod +x docker-start.sh ./docker-start.sh ``` -------------------------------- ### Copy Environment Example Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/multiagent/local_web_portal/README.md Copies the example environment file to a new file for local configuration. You can leave session and encryption keys empty for local testing; the app will generate fallback secrets. ```powershell Copy-Item local_web_portal\.env.example local_web_portal\.env ``` -------------------------------- ### Start Docker Services Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Build and start all services defined in the docker-compose.yml file in detached mode. ```bash docker-compose up -d ``` -------------------------------- ### Rebuild and Start Docker Services Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Rebuild the Docker images and start all services. Use this command after making code changes to ensure they are reflected. ```bash docker-compose up -d --build ``` -------------------------------- ### Install Project Dependencies Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/multiagent/local_web_portal/README.md Installs project dependencies using pip. Ensure you are in the project root directory. Use `python -m pip` if you have multiple Python versions. ```powershell python -m venv .venv .venv\Scripts\Activate.ps1 python -m pip install --upgrade pip setuptools wheel python -m pip install -r requirements.txt python -m pip install -r local_web_portal\requirements.txt ``` ```powershell python -m pip install -r requirements.txt python -m pip install -r local_web_portal\requirements.txt ``` -------------------------------- ### Start Local Web Server Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/multiagent/local_web_portal/README.md Starts the local web server using uvicorn. Add `--reload` for active development. For long-running jobs, running without reload is more stable. ```powershell python -m uvicorn local_web_portal.app.main:app --host 127.0.0.1 --port 8010 ``` -------------------------------- ### Manual PowerShell Startup Scripts Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md Execute these PowerShell scripts to manually set up the local environment, bootstrap shared virtual environment, and start all local services. Use the -Overwrite flag to replace existing configurations. ```powershell .\scripts\setup-local-env.ps1 -Overwrite .\scripts\bootstrap-shared-venv.ps1 .\scripts\start-all-local.ps1 -UseSharedVenv ``` -------------------------------- ### Configure Environment Variables Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Copy example environment files to their actual names. These files will contain sensitive information like API keys. ```bash # Copy example env files to actual .env files cp .env.auth-portal.example apps/auth-portal/.env cp .env.multiagent.example apps/multiagent/.env cp .env.novelclaw.example apps/novelclaw/.env ``` -------------------------------- ### Start Local NovelClaw Stack Source: https://github.com/ilearn-lab/novelclaw/blob/main/RUN_LOCAL_WEB.md Use this batch script to stop old listeners, write local environment files, prepare the shared virtual environment, and start the Portal, MultiAgent, and NovelClaw services. ```powershell .\START_LOCAL.bat ``` -------------------------------- ### Initial Render and Polling Setup - JavaScript Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/multiagent/local_web_portal/app/templates/job_detail.html Initializes the job detail view by rendering the initial snapshot and chapter outputs. It then sets up periodic polling for logs and chapters if auto-refresh is enabled. Event listeners are added for visibility change, focus, and online status to ensure polling resumes correctly. ```javascript renderSnapshot({{ snapshot|tojson }}); renderChapters({{ chapter_outputs|tojson }}); lastChaptersSignature = buildChaptersSignature({{ chapter_outputs|tojson }}); if (autoRefreshEnabled) { pollLogs(); document.addEventListener("visibilitychange", () => { if (!document.hidden && autoRefreshEnabled) scheduleNextPoll(100); }); window.addEventListener("focus", () => { if (autoRefreshEnabled) scheduleNextPoll(100); }); window.addEventListener("online", () => { if (autoRefreshEnabled) scheduleNextPoll(100); }); } ``` -------------------------------- ### Start Initialization Logic Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/dashboard.html Contains the main logic for starting the dashboard functionalities. It attempts to initialize features and falls back to a retry mechanism if immediate initialization fails. It also includes event listeners for 'load' and 'DOMContentLoaded'. ```javascript function start() { if (started) return true; {% if not chat_session.final_job_id %} var root = document.querySelector('\\[data-idea-copilot-root\\][data-layout="dashboard"]'). if (root && typeof window.initIdeaCopilotLive === 'function') { window.initIdeaCopilotLive(root); started = true; return true; } if (root && installFallbackIdeaLive(root)) { started = true; return true; } {% endif %} {% if chat_session.final_job_id %} var runRoot = document.querySelector('\\[data-chat-run-root\\]'); if (runRoot && typeof window.initChatRunLive === 'function') { window.initChatRunLive(runRoot); started = true; return true; } {% endif %} return false; } if (start()) return; var tries = 0; var timer = window.setInterval(function () { tries += 1; if (start() || tries >= 20) { window.clearInterval(timer); } }, 250); window.addEventListener('load', start, { once: true }); document.addEventListener('DOMContentLoaded', start, { once: true }); })(); {% endif %} ``` -------------------------------- ### Helpful Local Management Commands Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md Provides commands for stopping all local services and starting them with options for using a shared virtual environment or restarting existing services. ```powershell .\scripts\stop-all-local.ps1 .\scripts\start-all-local.ps1 -UseSharedVenv -RestartExisting ``` -------------------------------- ### Clone NovelClaw Repository Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Clone the NovelClaw repository to your local machine. Navigate into the cloned directory to proceed with setup. ```bash git clone https://github.com/iLearn-Lab/NovelClaw.git cd NovelClaw ``` -------------------------------- ### Displaying Planned External Connectors Count Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/console_mcp.html This snippet displays the count of planned external connectors. It uses a Jinja2 template filter to get the length of the 'external_connectors' list from the 'mcp_surface' object. ```html {{ ui_text('澶栭儴杩炴帴鍣紙璁″垝涓級', 'External Connectors (Planned)') }} **{{ mcp_surface.external_connectors | length }}** ``` -------------------------------- ### Prepare Environment Files for NovelClaw Components Source: https://github.com/ilearn-lab/novelclaw/blob/main/DEPLOYMENT.md Copies template environment files to the configuration directory and prepares them for customization. Edit the copied files to set production-specific values. ```bash sudo mkdir -p /etc/novelclaw sudo cp infra/env/auth-portal.env.template /etc/novelclaw/auth-portal.env sudo cp infra/env/multiagent.env.template /etc/novelclaw/multiagent.env sudo cp infra/env/novelclaw.env.template /etc/novelclaw/novelclaw.env ``` -------------------------------- ### Displaying Enabled Local Tools Count Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/console_mcp.html This snippet displays the count of enabled local tools. It uses a Jinja2 template filter to get the length of the 'enabled_local_tools' list from the 'mcp_surface' object. ```html {{ ui_text('宸插惎鐢ㄦ湰鍦板伐鍏?, 'Enabled Local Tools') }} **{{ mcp_surface.enabled_local_tools | length }}** ``` -------------------------------- ### Build Job Detail Items Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/job_detail.html Processes raw trace entries to build a list of items for rendering. It categorizes entries into different types like 'complete-banner', 'tool-card', and 'status-pill' based on event names. ```javascript function buildJdItems(entries) { const items = []; for (const entry of entries) { const { name, kv, jdToolMeta, entry: { stamp, detail } } = entry; if (name === 'claw_tool_result') { for (let i = 0; i < items.length; i++) { if (items[i].type === 'tool-card' && items[i].id.endsWith(`-${stamp}`)) { items[i].status = 'complete'; items[i].result = `reward=${kv.reward || '-'} | issues=${kv.issues || '-'} | length=${kv.length || '-'} chars`; break; } } continue; } if (name === 'claw_tool_running') { for (let i = 0; i < items.length; i++) { if (items[i].type === 'tool-card' && items[i].id.endsWith(`-${stamp}`)) { items[i].status = 'running'; items[i].result = null; break; } } continue; } if (name === 'claw_tool_error') { for (let i = 0; i < items.length; i++) { if (items[i].type === 'tool-card' && items[i].id.endsWith(`-${stamp}`)) { items[i].status = 'error'; items[i].result = kv.error || entry.detail || 'Unknown error'; break; } } continue; } if (name === 'claw_tool_progress') { for (let i = 0; i < items.length; i++) { if (items[i].type === 'tool-card' && items[i].id.endsWith(`-${stamp}`)) { items[i].status = 'running'; items[i].result = kv.progress || entry.detail || ''; break; } } continue; } if (name === 'claw_tool_card') { items.push({ type: 'tool-card', id: `tc-${stamp}-${kv.id || 'tool'}`, action: kv.action || 'call', meta: jdToolMeta(kv.tool || kv.action), step: kv.step || '-', status: 'pending', stamp: stamp, params: kv.params || entry.detail || '', result: null }); continue; } if (name === 'claw_loop_step') { if (items.length > 0 && items[items.length - 1].type === 'tool-card' && items[items.length - 1].status === 'running') { items[items.length - 1].status = 'complete'; items[items.length - 1].result = `reward=${kv.reward || '-'} | issues=${kv.issues || '-'} | length=${kv.length || '-'} chars`; break; } continue; } if (name === 'claw_finalize_ready' || name === 'claw_loop_complete') { items.push({ type: 'complete-banner', stamp: stamp, reason: kv.reason || entry.detail || 'Complete' }); continue; } if (name === 'claw_ask_user') { items.push({ type: 'tool-card', id: `tc-${stamp}-ask_user`, action: 'ask_user', meta: jdToolMeta('ask_user'), step: kv.step || '-', status: 'ask', stamp: stamp, params: kv.question || entry.detail || '', result: null }); continue; } if (name === 'claw_user_chapter_instruction') { items.push({ type: 'status-pill', stamp: stamp, label: `💬 User chapter instruction → ch${kv.chapter || '?'}` }); continue; } } return items; } ``` -------------------------------- ### View Docker Logs Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Tail the logs for all running services or a specific service. Use -f to follow the logs in real-time. ```bash # All services docker-compose logs -f # Specific service docker-compose logs -f novelclaw docker-compose logs -f multiagent docker-compose logs -f auth-portal ``` -------------------------------- ### Enter a Docker Container Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md Access a running container's shell for debugging purposes. Replace 'novelclaw-workspace' with the name of the target container. ```bash docker exec -it novelclaw-workspace bash ``` -------------------------------- ### Initialize Idea Copilot Live Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/dashboard.html Initializes the Idea Copilot live feature if the root element and the corresponding JavaScript function are available. This is conditionally executed based on the chat session's final job ID. ```javascript if (root && typeof window.initIdeaCopilotLive === 'function') { window.initIdeaCopilotLive(root); started = true; return true; } ``` -------------------------------- ### Dynamic Memory & Toolchain Relationship Description Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/console_mcp.html This section describes the dynamic memory and toolchain relationship, explaining that NovelClaw's current MCP-like capabilities are handled internally. It outlines the flow from LLM to function call, local sync tools, and memory bank writes, emphasizing no reliance on external MCP servers. ```html {{ ui_text('鍔ㄦ€佽蹇嗕笌宸ュ叿閾剧殑鍏崇郴', 'Dynamic Memory & Toolchain Relationship') }} {{ ui_text('NovelClaw 褰撳墠鐨?MCP-like 鑳藉姏瀹屽叏鐢卞唴閮ㄥ伐鍏烽摼鎵挎媴锛歀LM 鈫?function call 鈫?鏈湴 sync 宸ュ叿 鈫?memory bank 鍐欏叆銆備笉渚濊禆澶栭儴 MCP server锛涘閮ㄨ繛鎺ュ櫒锛堟祻瑙勭瓑锛堟槸鏈潵鎵╁睍鏂瑰悜銆? 'NovelClaw\'s current MCP-like capabilities are fully handled internally: LLM 鈫?function call 鈫?local sync tools 鈫?memory bank writes. No external MCP server required; external connectors (browser, publish) are future extensions.') }} ``` -------------------------------- ### Render Snapshot - JavaScript Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/job_detail.html Updates the UI with snapshot data for a job, including phase, timing, progress, and resource usage. Handles stall information. ```javascript function renderSnapshot(snapshot) { if (!snapshot) return; if (phaseLabelEl) phaseLabelEl.textContent = snapshot.phase_label || "-"; if (phaseNoteEl) phaseNoteEl.textContent = snapshot.phase_note || "-"; if (elapsedEl) elapsedEl.textContent = String(snapshot.elapsed_seconds ?? 0); if (idleEl) idleEl.textContent = snapshot.idle_seconds >= 0 ? String(snapshot.idle_seconds) : "-"; if (chapterProgressEl) { const cur = snapshot.current_chapter || 0; const total = Number(snapshot.planned_total || 0); chapterProgressEl.textContent = total > 0 ? `${cur}/${total}` : "-"; } if (chapterWordsEl) chapterWordsEl.textContent = String(snapshot.chapter_words ?? 0); if (totalWordsEl) totalWordsEl.textContent = String(snapshot.total_words ?? 0); if (progressBarEl) { const pct = Math.max(0, Math.min(100, Number(snapshot.percent || 0))); progressBarEl.style.width = `${pct}%`; } const mc = snapshot.memory_counts || {}; if (mcOutlinesEl) mcOutlinesEl.textContent = String(mc.outlines ?? 0); if (mcTextsEl) mcTextsEl.textContent = String(mc.texts ?? 0); if (mcCharactersEl) mcCharactersEl.textContent = String(mc.characters ?? 0); if (mcWorldsEl) mcWorldsEl.textContent = String(mc.world_settings ?? 0); if (mcFactsEl) mcFactsEl.textContent = String(mc.fact_cards ?? 0); if (stallHintEl) { if (snapshot.stalled) { stallHintEl.classList.remove("hidden"); stallHintEl.textContent = snapshot.stall_reason || ui.stall_fallback; } else { stallHintEl.classList.add("hidden"); stallHintEl.textContent = ""; } } } ``` -------------------------------- ### Initialize Chat Run Live Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/dashboard.html Initializes the chat run live feature if the root element and the corresponding JavaScript function are available. This is conditionally executed when a chat session has a final job ID. ```javascript if (runRoot && typeof window.initChatRunLive === 'function') { window.initChatRunLive(runRoot); started = true; return true; } ``` -------------------------------- ### Runtime Artifacts Paths Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md These are the key file paths for inspecting NovelClaw runtime data and logs. ```text apps/novelclaw/local_web_portal/data/app.db ``` ```text apps/novelclaw/local_web_portal/runs// ``` -------------------------------- ### Adjust File Permissions for Data Persistence Source: https://github.com/ilearn-lab/novelclaw/blob/main/DOCKER_DEPLOYMENT.md On Linux/Mac systems, you may need to adjust permissions for the data and runs directories to ensure Docker can write to them. ```bash chmod -R 755 apps/*/local_web_portal/data chmod -R 755 apps/novelclaw/local_web_portal/runs ``` -------------------------------- ### NovelClaw Repository Layout Source: https://github.com/ilearn-lab/novelclaw/blob/main/README.md An overview of the directory structure for the NovelClaw project. ```text . |-- apps/ | |-- auth-portal/ # public entry layer | |-- multiagent/ # optional fast ideation layer | `-- novelclaw/ # main writing workspace |-- scripts/ # local bootstrap / start / stop helpers |-- docs/ # screenshots and operator notes |-- infra/ | |-- nginx/ # reverse-proxy example | |-- systemd/ # service unit examples | `-- env/ # safe env templates only `-- state_snapshots/ # intentionally cleared for public-safe release ``` -------------------------------- ### Render Checkpoint JD - JavaScript Source: https://github.com/ilearn-lab/novelclaw/blob/main/apps/novelclaw/local_web_portal/app/templates/job_detail.html Renders a checkpoint card for a completed chapter, providing suggestions and an input area for user messages. Only renders if not already visible. ```javascript const CHECKPOINT_CHIPS_JD = [ 'Keep going — looks great!', 'Slow down and add more detail', 'Increase tension in next chapter', 'Focus more on character development', 'Add more world-building details', ]; const checkpointWrap = document.getElementById('chapter-checkpoint'); let checkpointVisible = false; function renderCheckpointJd(payload, runId) { if (!checkpointWrap || checkpointVisible) return; checkpointVisible = true; const chNo = payload.chapter || '?'; const planned = payload.planned_total || '?'; checkpointWrap.innerHTML = `
🏁
Chapter ${escapeHtml(String(chNo))} complete!
${escapeHtml(String(chNo))} of ${escapeHtml(String(planned))} · Claw waits for your input
Quick suggestions:
${CHECKPOINT_CHIPS_JD.map(c => `${escapeHtml(c)}`).join('')}