OpenClaw started in a broken state and now nothing works

An OpenClaw broken state after install is more common than it should be, and the symptoms are confusing: the service appears to be running, the gateway is up, but the agent does not respond to messages, tool calls fail immediately, or the UI loads but produces errors on every action. This article covers every cause of a broken first boot and gives you a systematic path to getting a fully working instance, in order from most common to least.

What a broken state actually looks like

Before diagnosing the problem, it helps to identify which kind of broken state you are in. The three patterns look similar from the outside but have different causes and fixes.

Pattern 1: Gateway is up, agent does not respond. You can reach the OpenClaw web UI or API endpoint. The service is running. But when you send a message, nothing comes back. No error, no partial response. This usually means the model is misconfigured, the API key is missing or invalid, or the agent session failed to initialize.

Pattern 2: Gateway fails to start. The OpenClaw service crashes immediately or exits after a few seconds. The web UI is unreachable. Attempting to reach the gateway URL gives a connection refused error. This usually means the config file has a syntax error, a required value is missing, or a port is already in use.

Pattern 3: Gateway starts, returns errors on every request. The service is up and responding, but every action fails. Tool calls return errors. The agent session produces stack traces or error messages instead of responses. This usually means a plugin failed to initialize, a dependency is missing, or the agent config references a resource that does not exist.

Step 1: Check gateway status and logs

The gateway is the process that runs OpenClaw. Whether it is running and what it logged at startup tells you almost everything you need to know about the cause of the broken state. This is always the first check, regardless of which pattern you are seeing.

Check the OpenClaw gateway status. Run a service status check and show me whether the process is running or stopped. Then show me the last 50 lines of the gateway service log. I am looking for error messages from startup, any mention of config file problems, missing API keys, failed plugin initialization, or port conflicts. Show me the exact error messages if any are present.

The log output at startup is diagnostic gold. OpenClaw logs what it is doing as it initializes. If it hit a problem, the log will say exactly where it stopped and why. Common startup log patterns and what they mean:

• “No API key configured” or “model provider not set”: The agent has no model to call. It will accept messages but cannot respond to any of them. Fix is in Step 2 below.
• “Unexpected token” or “SyntaxError” in openclaw.json: The config file has invalid JSON. The gateway cannot parse its own config. Fix is in Step 3 below.
• “Plugin X failed to load” or “Error initializing plugin”: A plugin crashed during startup. Depending on the plugin, this may or may not affect the rest of the agent. Fix is in Step 4 below.
• “Address already in use” or “EADDRINUSE”: Something else on the server is using the port OpenClaw wants. Fix is in Step 5 below.
• “Cannot find module” or “MODULE_NOT_FOUND”: A Node.js dependency is missing. This typically happens after an interrupted installation. Fix is in Step 6 below.

Step 2: Verify the API key and model configuration

An API key is a credential that gives OpenClaw permission to use an AI model service. When you install OpenClaw, it ships with a default config that references a model provider (Anthropic, OpenAI, OpenRouter, or a local Ollama instance). If no API key is set for that provider, or if the key is invalid, the agent starts successfully but cannot generate any responses. Every message you send disappears into silence.

This is the single most common cause of a broken state after first install. The installation completes, the service starts, everything looks fine, but the agent cannot do anything because it has no way to call a model.

Read my openclaw.json and tell me: what model provider is configured as the primary model, what API key is set for that provider (show the first 8 characters only, not the full key), and whether a fallback model is configured. If the API key field is empty, set to a placeholder like “YOUR_API_KEY_HERE”, or missing entirely, tell me that explicitly. Also tell me whether Ollama is configured as a local model option and whether it appears to be reachable.

If the API key is missing, the fastest fix depends on which model provider you plan to use. The most common starting points:

• Anthropic (Claude): Get your API key from console.anthropic.com. The config field is typically models.providers.anthropic.apiKey.
• OpenAI: Get your API key from platform.openai.com. The config field is typically models.providers.openai.apiKey.
• OpenRouter: Get your API key from openrouter.ai. OpenRouter gives access to many models through one key and is often the most cost-effective starting point.
• Ollama (local models): Ollama does not use API keys. You need Ollama installed on your machine or server and at least one model downloaded. If you want to run entirely locally at zero API cost, Ollama is the path.

I have my API key ready. Update my openclaw.json to set the [provider] API key to [YOUR KEY]. Do not show the key back to me in your response. After updating the config, restart the OpenClaw gateway so the change takes effect. Once restarted, send a test message to verify the model is responding correctly. Tell me the model name and the response you get.

Step 3: Fix a broken config file

The openclaw.json config file is written in JSON format. JSON is strict about syntax: a single missing comma, an extra bracket, or an unescaped quote will make the entire file unreadable. When OpenClaw reads its config on startup and encounters invalid JSON, it cannot initialize and the gateway will either fail to start or start in a degraded state with default values that may not match your intended setup.

Config file corruption happens most often when someone edits openclaw.json manually, when a partial write occurs during a crash, or when a copy-paste operation introduces incorrect characters.

Read my openclaw.json file and check it for JSON syntax errors. Parse it and tell me whether it is valid JSON. If it has errors, show me exactly which line and character position has the problem, what the error is, and what the correct syntax should be. Do not modify the file yet, just tell me what is wrong.

Before applying any fix, note that restarting the gateway with invalid JSON produces a silent failure: the restart command completes without error, but the gateway exits immediately because it cannot parse the config. Always validate the JSON before restarting, not after.

Once you know what is wrong, fixing it is usually straightforward. The most common JSON errors and their fixes:

• Trailing comma on the last item in an object or array. JSON does not allow a comma after the final item before a closing bracket. Remove the comma.
• Single quotes instead of double quotes. JSON requires double quotes for all strings. Single quotes are not valid.
• Unescaped backslash in a Windows file path. Backslashes in JSON strings must be doubled: \\ not \. A Windows path like C:\Users\name must be written as C:\\Users\\name.
• Missing closing bracket or brace. Every { needs a matching } and every [ needs a matching ]. A missing bracket at the end of the file is the most common cause of this error.
• Comment in the file. JSON does not support comments. If you added a // or /* */ comment to openclaw.json, it will break parsing. Remove all comments.

Fix the JSON syntax error you found in my openclaw.json. Make the minimal change needed to produce valid JSON. After fixing it, read the file back and confirm it parses without errors. Then restart the OpenClaw gateway and tell me whether it starts cleanly.

Step 4: Resolve plugin initialization failures

Plugins are optional extensions that add capabilities to OpenClaw: memory systems, channel integrations (Telegram, Discord), external tool connectors, and more. When a plugin fails to initialize at startup, it logs an error and OpenClaw continues without it. This is the intended behavior for non-critical plugins. The problem occurs when a plugin that is critical to your workflow fails, or when a plugin failure produces a cascade that affects other parts of the agent.

Check the gateway startup logs for any plugin initialization errors. List every plugin that failed to load, the exact error message for each, and whether each failed plugin was marked as required or optional in my config. For each failed plugin, tell me the most likely cause based on the error message.

Plugin failures fall into four categories:

• Missing dependency: The plugin requires another package (an npm module, a system binary, or an external service) that is not installed. The error message usually names the missing dependency.
• Invalid config: The plugin has required config fields that are missing, empty, or have wrong values. Common examples: a memory plugin that needs a database path, a Telegram plugin missing a bot token, an Ollama plugin pointing to the wrong port.
• Version mismatch: The plugin was built for a different version of OpenClaw than the one you have installed. As of March 2026, the recommended approach is to check the plugin’s documented compatibility page on clawhub.com or its npm package page and update either the plugin or OpenClaw to a matching version. Plugin version mismatches often produce cryptic errors rather than a clear “incompatible version” message, so checking the compatibility matrix is worth doing even when the error message does not mention versioning.
• External service unreachable: The plugin connects to an external service at startup and that service is down or unreachable. Memory plugins that use a remote database, embedding plugins that call an external API, and channel plugins that need to register webhooks can all fail this way.

For each plugin that failed to initialize, tell me what I need to do to fix it. If a plugin requires a missing config value, show me where in openclaw.json that value should go and what format it expects. If a plugin has a dependency I need to install, tell me the exact install command. If a plugin is optional and I do not need it right now, tell me how to disable it so it does not produce errors on every startup.

Step 5: Resolve port conflicts

A port is a numbered channel on your computer or server that applications use to receive network connections. Each port can only be used by one application at a time. OpenClaw’s gateway runs on a specific port (18789 by default). If something else on the same machine is already using that port when OpenClaw starts, OpenClaw cannot bind to it and will fail to start or start in a partial state.

Port conflicts are most common in two situations: you installed a second OpenClaw instance on the same machine without changing the port, or another application (a web server, a database, a different agent) happens to be using the same port number.

Check whether the OpenClaw gateway port is already in use. Run a port check for the port configured in my openclaw.json gateway settings. Tell me what process is using that port if anything is, and whether it is another OpenClaw instance or something else. If there is a conflict, tell me my options for resolving it.

Resolving a port conflict has two paths: change the port OpenClaw uses, or stop the process that is occupying the port. If you are running a second OpenClaw instance intentionally, change one instance to use a different port (18790, for example) and update any clients or channel webhooks that reference the old port. If the conflict is with an unrelated application and you do not want to stop that application, the same approach applies. The port change requires a single config update in openclaw.json under the gateway section, followed by a restart. After changing the port, any external URL you use to reach the gateway (webhook URLs, mobile app connections, reverse proxy configs) will also need to be updated to reference the new port number.

Step 6: Fix missing Node.js dependencies

OpenClaw runs on Node.js and uses a set of JavaScript packages (called dependencies) to function. These dependencies are normally installed automatically during the OpenClaw installation process. If the installation was interrupted, ran out of disk space, encountered a network error, or was performed with insufficient permissions, some dependencies may not have installed correctly. The result is a startup that fails with MODULE_NOT_FOUND errors.

Check the gateway logs for any MODULE_NOT_FOUND or dependency-related errors. If you find any, tell me the exact module name that is missing and what command I should run to reinstall OpenClaw’s dependencies. Also check whether there are any obvious signs of an incomplete installation in the OpenClaw directory.

The fix for missing dependencies is almost always running the dependency install command from the OpenClaw installation directory. This reinstalls any missing packages without affecting your config file or workspace data. Ask your agent for the exact command for your installation type, or check the OpenClaw docs at docs.openclaw.ai for the installation-specific reinstall steps. On npm-based installs, the command is typically npm install run from the OpenClaw app directory. On package-managed installs (homebrew, apt, or similar), updating the package through the same package manager that installed it will repair missing dependencies without wiping your config.

Step 7: Verify the full stack is working

Once you have addressed the specific error from the startup logs, run a full stack verification before considering the problem resolved. A partial fix that leaves one component still broken will produce intermittent failures that are harder to diagnose than the original error.

Run a full health check of my OpenClaw installation. I need to verify: the gateway started cleanly with no errors, at least one model is configured and responding, all plugins I have enabled initialized without errors, the workspace directory is accessible, and memory is functioning if I have a memory plugin installed. For each item, tell me the current status and flag anything that is not working.

Send a simple test: what is 2 plus 2? Then run a file read: show me the first 5 lines of my openclaw.json. Both of these should work without errors. If either fails, tell me the exact error. The math test confirms the model is working. The file read confirms tool calls are working. If both pass, my installation is functional.

If both tests pass, your installation is working. If the math test fails, the model is still not configured correctly. Go back to Step 2 and verify the API key is set for the correct provider, the model name is valid for that provider, and the gateway restarted after your last config change. If the math passes but the file read fails, the exec or file tools are blocked or disabled. Check the agents.defaults.tools section of your config for any tool restrictions that may have been set, and verify the exec approval policy is not set to “deny” for all commands. If both tests fail, the gateway is running but the agent session is not initializing. Check the logs for agent initialization errors specifically, which are separate from gateway startup errors.

First boot: what to do before you start OpenClaw for the first time

If you have not started OpenClaw yet and want to avoid the broken state entirely, there is a short checklist that prevents the most common first boot failures. Running through this before your first start takes five minutes and saves the diagnostic loop above.

• Set at least one API key before starting. OpenClaw cannot do anything without a model. Open openclaw.json and add your API key before the first start. The gateway will start without it but the agent will be non-functional.
• Validate the JSON after editing. Any manual edit to openclaw.json can introduce a syntax error. Run a JSON validation pass before starting OpenClaw for the first time after editing the config.
• Check whether port 18789 is free. If you are on a shared server or have other services running, verify the default OpenClaw port is not already in use before starting.
• Verify disk space. You need at least 500MB of free space for OpenClaw to operate. For memory plugins and local model caching, 5GB or more is recommended.
• Note your gateway bind address. If you set gateway.bind to 0.0.0.0, the gateway is reachable from outside your server. If you want it loopback-only, set it to 127.0.0.1 before the first start. Changing it after you have active integrations may break channel connections that depend on external access. If you plan to connect Telegram or Discord bots via webhooks, you need the gateway to be externally reachable either directly or via a reverse proxy. If you are using polling-based integrations only, loopback is safe.

I am about to start OpenClaw for the first time. Before I do, review my openclaw.json and tell me: is the JSON valid, is at least one API key set with a non-placeholder value, is the gateway port free, are there any required config fields that are empty or missing, and are there any plugins enabled that are missing required config. Give me a go or no-go with specific items to fix if it is a no-go.

FAQ

Three things to check after the API key is set. First, confirm the gateway actually restarted and loaded the new config. Ask your agent to show you the current primary model name. If it shows a placeholder or a different provider than you configured, the restart did not apply the new config. Check that the config file was saved before restarting. Second, confirm the API key is valid by checking for errors in the gateway logs after the first message attempt. An invalid key returns a 401 error from the model provider that appears in the logs but may not surface as a visible error to the user. Third, check whether you have a model name configured alongside the API key. Some provider configs require both a key and an explicit model name. If the model field is empty, the provider call may fail even with a valid key.

A gateway that starts and then exits quickly is usually hitting an error in the initialization sequence after the initial startup message. The key is to capture logs from the moment of the crash. On Linux, run journalctl -u openclaw -f in one terminal window (the -f flag follows the log in real time), then restart the gateway in another window. Watch the log for the last message before the process exits. That message is the error. On macOS and Windows, the equivalent is following the log output in the terminal where you launched OpenClaw manually. The crash message will be the last line before the process exits.

A complete reset restores openclaw.json to the factory defaults, which removes all your customizations but guarantees a clean start. Before doing this, back up your current openclaw.json by copying it to a different filename. Then ask your agent to show you the default config template or check the OpenClaw docs at docs.openclaw.ai for the latest default config. Replace openclaw.json with the template, add only your API key and essential settings, and restart. If the clean config starts correctly, add your customizations back one section at a time, restarting after each change, until you find the setting that was causing the problem.

Four things cause this pattern. First, an API key that hit its spending limit or was revoked by the provider. Model API keys can be automatically suspended when they exceed a spending threshold. Check your provider’s dashboard for any alerts or billing issues. Second, an OpenClaw auto-update that introduced a config change. If auto-update is enabled and ran overnight, the new version may have changed a config field name or default that your existing config no longer matches. Check the OpenClaw changelog for the version that installed. Third, a plugin that depends on an external service that went down. Memory plugins, embedding plugins, and channel plugins can all break if their external dependency becomes unreachable. Fourth, disk full. If your server ran out of disk space overnight, the gateway may still start but fail on any operation that requires writing to disk, which is nearly everything. Log writes, memory writes, session saves, workspace file operations: all of these require disk space. A server that runs out of disk overnight often shows the same symptoms as a model failure because the agent accepts messages but produces no output. Check disk space first whenever you see a spontaneous failure with no corresponding API or model error in the logs.

Yes. If you have Ollama installed with at least one model downloaded, you can configure OpenClaw to use only Ollama and no external API keys. The setup requires Ollama running on port 11434 (the default) and at least one model pulled, for example phi4 or llama3.1:8b. Ask your agent to show you the Ollama provider config in openclaw.json and verify the model name matches a model you have downloaded locally. Running entirely on local models means no API costs and no key management, at the cost of slower responses and less capable models for complex tasks.

Not directly. A missing SKILL.md message is a warning about the skills directory, not a core startup error. Skills are optional instructions that teach the agent how to do specific tasks. If a skill is configured but the SKILL.md file is missing, the agent logs a warning but continues to function. This message appearing at startup does not indicate a broken installation. However, if you configured a skill path in your agent config and the file genuinely does not exist, you should either remove the skill reference from your config or provide the SKILL.md file at the expected path. Ask your agent to list all configured skill paths and check which ones have missing files.

No. A context window exceeded error on the first message usually means the startup system prompt, injected memories, or workspace files are collectively too large for the model’s context limit. This is a configuration issue, not a broken installation. The fix is either to use a model with a larger context window, reduce the size of your system prompt or injected context, or adjust the compaction settings so the agent trims context before hitting the limit. Ask your agent to report the total token count of the startup context and which sections are consuming the most tokens.

What not to do when OpenClaw is in a broken state

When something is broken and nothing is working, the instinct is to try everything fast: reinstall, wipe config, restart repeatedly. These actions often make the diagnosis harder and occasionally make the problem worse. Three specific things to avoid:

Do not reinstall before reading the logs. A reinstall replaces the application files but does not fix a config problem, a missing API key, or a port conflict. If the root cause is in openclaw.json, reinstalling leaves you with the same broken config and a fresh copy of the application on top of it. Read the startup logs first. The cause is almost always there.

Do not restart repeatedly without changing anything. If the gateway logs the same error every time it starts, restarting again will log the same error again. Repeated restarts do not fix errors. One restart after making a specific change is the correct pattern. Restart without a change tells you nothing new and risks log rotation burying the original error.

Do not edit openclaw.json while the gateway is running. OpenClaw reads its config at startup. Edits made while the gateway is running are not applied until the next restart. If you edit the file and the gateway continues running, you may not realize your changes did not take effect and spend time diagnosing a config problem that is already fixed but not yet active. Make the edit, verify the JSON is valid, then restart. Throughout this article, “restart the gateway” means running the appropriate restart command for your install type. On systemd Linux installs, that is systemctl restart openclaw. On manual installs, it is stopping and relaunching the process. Ask your agent which restart method applies to your setup if you are unsure.

Before I make any more changes to fix this broken state, summarize what you know about the current state of my OpenClaw installation based on the logs and config you have read. Tell me: what is the most likely root cause, what is the minimal change needed to fix it, and what I should verify after making that change to confirm it is resolved.

Getting a root cause summary before making changes is the single most valuable thing you can do in a broken state. It prevents the common pattern of applying multiple overlapping fixes that make it impossible to know which one actually resolved the problem. When you apply fix A and fix B simultaneously and the agent starts working, you have not learned which one was the issue. If it breaks again in a week, you are back to guessing. Isolate one variable at a time, test, then move to the next. The diagnostic takes longer upfront but produces a clean known-working state rather than a working state you cannot fully explain. A working state you cannot explain is one broken deployment away from becoming a mystery you have to solve under pressure. Understand the fix now.

Getting a second diagnostic read

If you have been working on the broken state for more than 15 minutes and the root cause is still unclear, start a fresh diagnostic from the beginning. Diagnostics that run long tend to accumulate assumptions: “I already checked X” or “it must be Y because I already ruled out Z.” Starting fresh with a clean prompt often surfaces the actual cause faster than continuing on an assumption-laden path. The fresh diagnostic prompt below takes about 60 seconds and frequently identifies the root cause in one pass, even for problems that have been open for much longer.

I have an OpenClaw installation in a broken state and I want a fresh diagnostic. Forget everything we have discussed. Read my openclaw.json from scratch, check the current gateway status, read the last 100 lines of gateway logs, and tell me the top three most likely causes of the problem based solely on what you see now. Rank them by likelihood and tell me the fastest way to test each hypothesis. For each hypothesis, tell me what I should see if it is correct and what one change would confirm or rule it out.

Keep Reading: