Self-Hosted AI Assistant on Windows 11: Installation and Model API Integration Guide

    This guide explains how to install and configure a self-hosted AI assistant on Windows 11. It compares deployment options, outlines the system architecture, prepares the required environment, shows how to install the platform, connect a cloud large language model API, extend capabilities with skills, and apply security and operational hardening.

    1. Why Choose a Self-Hosted AI Assistant?

    General-purpose cloud AI assistants work out of the box, but enterprises and developers often face several issues:

    • Data concerns: Business documents, source code, and internal materials are uploaded to third-party services, making it difficult to control where data is stored and how long it persists.
    • Limited control: Model versions and policies may be changed by the platform provider without notice. Prompts, conversation history, and tool-call flows are hard to audit.
    • Limited customization: General-purpose products often make it difficult to extend tools and skills for specific business workflows.

    A self-hosted AI assistant platform is an assistant system deployed inside an environment you control. Such platforms typically provide a chat entry point, model routing, skill expansion, and other capabilities. The underlying large language model can be connected through an API. The features commonly associated with this product category, such as local data storage, flexible model switching, extensible skills, and a web console, reflect this deployment model.

    The value of a self-hosted AI assistant can be summarized in four points:

    1. Clear data boundaries: Conversation records, uploaded files, and call logs remain on local disks. You can decide whether and when to send data to the model service.
    2. Independent model selection: By changing configuration, you can switch between or combine models from different providers and model tiers.
    3. Extensible capabilities: Through plugins or skill mechanisms, you can add file processing, web search, knowledge base retrieval, scheduled tasks, and other capabilities. Over time, a general assistant can become a business-aligned digital coworker.
    4. Complete interaction experience: A web console is usually the primary interface, with additional support for command-line interaction and external APIs. This makes the system useful for individual use and easier to integrate into other systems.

    It is also important to understand the limitations:

    • The platform depends on local devices. If the device is powered off, the service becomes unavailable.
    • You are responsible for operational work such as updates, backups, and security hardening.
    • Model calls still depend on external services. Usage fees and network quality directly affect the experience.

    2. Choosing a Deployment Model and Understanding the Architecture

    2.1 Comparison of Three Common Approaches

    Approach How It Works Main Advantages Main Costs
    Approach 1: Pure cloud assistant Uses a vendor-hosted online assistant entirely Easy to start, no maintenance required Data and conversations are fully hosted externally
    Approach 2: Local platform + cloud model API The assistant platform is self-hosted and data stays local; inference is performed through cloud LLM services Balances privacy, model capability, and deployment cost When data leaves the local machine, it depends on external service terms and network quality
    Approach 3: Fully local inference Both the platform and the model run locally Data stays within the internal network High memory and GPU requirements; limited model capability

    For individual users and most small or medium-sized teams, Approach 2 offers the best balance among capability, cost, and privacy. It does not require purchasing high-end GPUs to run models locally, while conversation data and operation processes can remain on the local machine.

    This article uses Approach 2 as the main path and explains how to evolve toward Approach 3 as needed.

    2.2 Layered Architecture

    A self-hosted AI assistant platform usually includes the following layers:

    • Access layer: Web console, command-line interface, HTTP API, and adapter modules for connecting to third-party communication and collaboration platforms.
    • Orchestration and session layer: Manages sessions, maintains context, interprets user intent, and decides whether the model should answer directly or call a skill.
    • Model adapter layer: Hides differences between provider APIs, calls chat completion endpoints in a unified way, and supports multi-model configuration, failover, and streaming output.
    • Skill and tool layer: Provides extensible capabilities such as file processing, web search, and scheduled tasks through plugins.
    • Data layer: Local databases, configuration files, conversation records, and uploaded files.
    • Operations and security layer: Access authentication, transport encryption, logging, monitoring and alerting, and backups.

    Understanding this layered structure helps you determine the role of each configuration item during installation and later expansion.

    3. Preparation

    3.1 Hardware and System Requirements

    Item Minimum Requirement Recommended Configuration
    Operating system Windows 10 64-bit Windows 11 64-bit, updated to the latest version
    Processor x64 processor supporting 64-bit instruction sets 4 cores or more
    Memory 8 GB 16 GB or more
    Disk 2 GB of free space 10 GB or more reserved
    Network Can reach the model service endpoint Stable network with low latency

    Additional notes:

    • The platform itself is lightweight: The 2 GB requirement refers only to installing the platform itself. If you later enable local knowledge bases, vector retrieval, or store large amounts of conversation data and files, disk usage will increase significantly. Reserve enough space in advance.
    • Local inference requires separate evaluation: If you later want to try Approach 3 and run models locally, a discrete GPU with less than 8 GB of VRAM often struggles to run larger models smoothly. Hardware should be evaluated separately.
    • Keep the system up to date: Applying system updates in time can reduce compatibility issues with runtime dependencies.

    3.2 Obtaining a Large-Model API Key

    The API key is the credential that allows the assistant to call model capabilities. The process is similar across providers. A typical flow is as follows:

    1. Create an account with a model provider and complete any required verification.
    2. Enable the relevant model service. Review the model list, calling methods, and pricing rules.
    3. Create an API key or application credential in the provider console. Copy it and store it securely.
    4. Review the endpoint URL, model identifier, context length, and any free-tier quota for the model you plan to test.

    Pay special attention to the following points:

    • Create keys with least privilege: Create a dedicated key only for this assistant. Do not use a personal main account key for experiments.
    • Avoid plaintext leakage: Do not hardcode the key into source code or configuration files. Do not share screenshots or commit it to a repository.
    • Make rotation easy: If a key is leaked or suspected of being compromised, disable it immediately in the provider console and generate a new one.
    • Watch free-tier quotas: Many providers offer free quotas or limited-time free access for lightweight models. Refer to the official pricing documentation. It is usually best to validate the full pipeline with a low-cost model first, then switch to the target model.

    3.3 Open an Administrator Terminal

    1. Press Win + X, then choose Windows PowerShell (Administrator) or Terminal (Administrator).
    2. If the User Account Control prompt appears, select Yes.
    3. Run whoami /groups to review the current account privilege groups and confirm that the session is running at a high integrity level.

    Administrator privileges are required during installation because the process writes to system directories and modifies environment variables. For daily operation, it is recommended to switch back to a standard user account.

    4. Installing the AI Assistant Platform

    4.1 Prerequisites: Runtime and Execution Policy

    Most platforms of this type are built on a mainstream JavaScript runtime. This runtime usually follows a release convention where even-numbered versions are long-term support releases. Installation scripts generally detect and install a suitable long-term support version automatically. If you choose manual installation, select a version that matches the platform requirements.

    Some platforms provide a one-click installation script. Because the default execution policy may block script execution, you may need to run the following command in an administrator terminal first:

    1. Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
    2. # When prompted whether to change the execution policy, type Y and press Enter

    RemoteSigned means that locally created scripts can run, while scripts downloaded from the network must have a trusted digital signature. This is a balance between usability and security. It is not recommended to loosen the policy to Unrestricted or Bypass just for convenience.

    4.2 Installation Steps

    Method 1: One-click installation script (recommended)

    The official installation address should be obtained from the project’s official documentation. After obtaining the address, review the script before running it:

    1. # Download the script locally and review it manually first
    2. iwr -useb <official-install-script-url> -OutFile "$env:TEMP\install-ai-assistant.ps1"
    3. notepad "$env:TEMP\install-ai-assistant.ps1"
    4. # Run it after confirming that it is safe
    5. & "$env:TEMP\install-ai-assistant.ps1"

    The script usually completes the following tasks automatically: detecting and installing the runtime, downloading platform core files, writing required system paths, and prompting for initial configuration.

    Method 2: Global installation with a package manager

    If a suitable runtime and its package manager are already installed, you can install the platform command-line tool globally:

    1. # First configure or switch to the official package mirror, then run the installation
    2. npm install -g <platform-package>@<target-version>

    This method is convenient for updates and is better isolated from other system projects.

    Method 3: Container deployment (optional)

    Running multiple services on the same machine is often easier with containers because they provide isolation and portability. Note that you must map the data directory and configuration directory into the container. Otherwise, data may be lost when the container is rebuilt.

    Notes:

    • Installation usually takes 3 to 10 minutes, depending on network conditions. Do not close the terminal window during installation.
    • After installation, if a newly added command is not recognized, close and reopen the terminal so that environment variables take effect.
    • In enterprise environments, software distribution policies or endpoint protection tools may block scripts. In that case, consult your IT administrator before proceeding.

    4.3 Strategies for Network-Restricted Environments

    1. Use package mirrors: Configure the package manager to use official or trusted mirrors to speed up runtime and dependency downloads.
    2. Use official installation entry points: Some projects provide mirror installation addresses. Obtain them from official documentation. Do not use unknown “acceleration scripts.”
    3. Install offline: Download the installer and dependencies, then transfer them to the target machine. For container deployments, you can also export image files in a networked environment and import them into an offline environment.
    4. Configure a proxy: If you have a compliant proxy, set HTTPS_PROXY and HTTP_PROXY environment variables.

    4.4 Verify the Installation

    1. # Check the platform version
    2. openclaw --version
    3. # Run the environment check (the exact subcommand may vary by official documentation)
    4. openclaw doctor

    Check the following points:

    • The version number is printed correctly, and no missing runtime is reported.
    • The self-check results show no errors related to network, ports, or permissions.
    • After starting the web service, run netstat -ano | findstr :3000 to confirm that the port is listening. Port 3000 is a common default for this type of platform.

    5. Connecting a Large-Model API

    5.1 Configuration Items

    Configuration structures vary across platforms, but the core items can be summarized as follows:

    Configuration Item Purpose Notes
    Base URL Specifies the model service endpoint Whether it includes a version path must match the official documentation exactly
    API key Authentication credential Inject through environment variables or a secret management tool
    Model identifier Specifies the exact model to call Must exactly match the name in the model list
    Generation parameters Temperature, maximum output length, system prompt, and so on Lower temperature produces more stable output; higher temperature produces more diverse output
    Timeout and retry Controls waiting time and failure recovery Retries should use exponential backoff to avoid amplifying failures
    Multi-model configuration Primary and backup models, or task-based routing Useful for fallback switching and cost control

    5.2 Write the Key and Configuration File

    First, add the key to the current user’s environment variables:

    1. # Applies only to the current terminal session; useful for temporary testing
    2. $env:MODEL_API_KEY = "<your-api-key>"
    3. # Persists the environment variable for the current user; new terminals will pick it up automatically
    4. [Environment]::SetEnvironmentVariable("MODEL_API_KEY", "<your-api-key>", "User")

    Then reference the variable in the configuration file:

    1. # Model integration example; field names depend on the platform documentation
    2. models:
    3. default:
    4. base_url: "https://<model-provider-endpoint>/v1"
    5. api_key_env: "MODEL_API_KEY" # Read the key from an environment variable to avoid plaintext storage
    6. model: "<model-identifier>"
    7. params:
    8. temperature: 0.3
    9. max_output_tokens: 2048
    10. timeout_seconds: 60

    5.3 Verify Model Connectivity

    Before configuring the platform, it is recommended to call the model endpoint directly from the command line to confirm that the key, endpoint, and model name are correct:

    1. $body = @{
    2. model = "<model-identifier>"
    3. messages = @(
    4. @{ role = "user"; content = "Describe yourself in one sentence." }
    5. )
    6. temperature = 0.3
    7. } | ConvertTo-Json -Depth 5
    8. $headers = @{ Authorization = "Bearer $env:MODEL_API_KEY" }
    9. Invoke-RestMethod -Uri "https://<model-provider-endpoint>/v1/chat/completions" `
    10. -Method Post -Headers $headers -ContentType "application/json" -Body $body

    This format follows the common structure used by mainstream chat completion APIs, including authentication headers, message lists, and generation parameters. If the response contains a candidate reply field, the connection is working. You can then use the same parameters in the platform configuration.

    5.4 Model Switching and Combined Use

    • Task-based routing: Use models with stronger reasoning capability for long-document understanding and coding tasks. Use lightweight, lower-cost models for routine question answering.
    • Failure fallback: Configure primary and backup models. If the primary model is rate-limited or encounters a service error, the system can switch to the backup model automatically.
    • Cost observation: Platform usage statistics or call logs can serve as a basis for cost evaluation and help identify high-frequency consumption scenarios.

    6. Skill Expansion and Multi-Client Access

    The core value of the platform lies in extensibility. Through skills or plugins, the assistant can evolve from “only chatting” to “actually getting work done”:

    • File processing: Read, convert, and organize local documents and spreadsheets. Validate output formats to prevent abnormal content from overwriting original files.
    • Web search: When real-time information is needed, a skill performs retrieval and provides organized results for the model to summarize.
    • Knowledge base retrieval: Split internal documents, vectorize them, and store them in a local vector database. The model can answer based on retrieved results, which helps reduce hallucinations.
    • Scheduled tasks: Periodically summarize information, generate reports, or run inspections.
    • Multi-client access: Use adapter modules provided by the platform to connect to common enterprise instant messaging and collaboration platforms, making the assistant available inside daily team workflows.

    When extending skills, follow these principles:

    1. Least privilege: Grant each skill only the directory, command, and network permissions required to complete its task.
    2. Auditable sources: Prefer skills from official or trusted sources, and review the skill list regularly.
    3. Interactive confirmation: High-risk skills involving deletion, overwriting, or external transmission should require human confirmation.
    4. Sandbox isolation: Skills that execute code should run in containers or restricted user accounts.

    7. Security Hardening and Production Readiness

    Self-hosting means security responsibilities also shift to you. The following areas should be hardened:

    • Network exposure: By default, listen only on the loopback address (127.0.0.1). If local-area network or remote access is required, enable the platform’s access authentication and configure HTTPS through a reverse proxy. Do not directly expose the port to the public internet.
    • Key management: Inject keys only through environment variables or a secret management service. Mask sensitive values in logs and establish a regular rotation mechanism.
    • Update policy: Keep the platform and runtime versions up to date to fix known vulnerabilities. Back up data before upgrading and validate the upgrade in a test environment first.
    • Data backup: Back up configuration files and data directories regularly. Important data can be incrementally backed up to cloud storage such as object storage.
    • Observability: Forward platform logs to a logging service. Use monitoring and alerting to cover service availability, response latency, and abnormal call volume.
    • Cost control: Set monthly budget alerts for model calls to avoid unexpected costs caused by abnormal loops or excessive invocation.

    8. Troubleshooting

    • Error message: “Unable to load file because running scripts is disabled on this system.”
      Possible cause: Execution policy restriction.
      Resolution: Set the current user’s execution policy to RemoteSigned as described in Section 4.1.

    • Error message: The command is not recognized as an internal or external command.
      Possible cause: Environment variables were not refreshed after installation.
      Resolution: Close and reopen the terminal. If necessary, check the system path configuration.

    • Problem: The installation script download is slow or interrupted.
      Possible cause: Network restrictions.
      Resolution: Switch to an official mirror or installation entry, or use offline installation.

    • Problem: The port is already in use.
      Possible cause: Another program is using the service port.
      Resolution: Run netstat -ano | findstr :3000 to identify the process using the port, then stop that process or change the platform port.

    • Problem: The model API returns an authentication failure.
      Possible cause: The key is invalid, expired, or lacks sufficient permissions.
      Resolution: Verify the key and its authorization relationship with the model service. Regenerate the key if necessary.

    • Problem: The model API returns a path-not-found error.
      Possible cause: The endpoint URL is missing or contains an extra version path.
      Resolution: Correct the endpoint address according to the official API documentation.

    • Problem: The model API returns a too-many-requests error.
      Possible cause: Rate limiting has been triggered.
      Resolution: Add exponential backoff retries, reduce concurrency, or request a higher quota.

    • Problem: The web console cannot be accessed from the local-area network.
      Possible cause: The service is listening only on the local machine, or a firewall is blocking access.
      Resolution: Change the listening address if needed, and allow the corresponding port in the firewall. This should be done only after authentication and HTTPS are properly configured.

    9. Conclusion

    Self-hosting an AI assistant on Windows 11 means taking control of both intelligent capabilities and data boundaries. The implementation path can be summarized as follows:

    1. Choose the right approach: Use “local platform + cloud model” to balance privacy, capability, and cost.
    2. Prepare properly: Confirm hardware requirements and apply for API keys using the least-privilege principle.
    3. Install methodically: Review installation scripts, verify before use, and choose mirrors or offline methods when the network is restricted.
    4. Connect securely: Inject keys through environment variables, verify model connectivity first, and configure primary and backup models.
    5. Maintain continuously: Extend capabilities through skills, and protect the system with authentication, encryption, backups, and monitoring.

    For teams with sensitive data or deep customization needs, this approach has strong practical value. If there is a stronger requirement later to keep data entirely within the internal network, you can gradually replace cloud model calls with local inference models when local GPU memory permits, achieving a smooth evolution.