# OpenClaw 端口无法监听：完整故障排除指南 [2026]

> 通过这份完整指南解决 OpenClaw 端口问题。诊断网关端口 18789、控制服务 18791、CDP 中继 18792 和托管浏览器端口。包含所有平台的分步解决方案。

- Source: https://www.aifreeapi.com/zh/posts/openclaw-port-not-listening
- Language: zh
- Published: 2026-02-04
- Updated: 2026-10-09
- Publisher: AI Free API (https://www.aifreeapi.com)

OpenClaw 通过精心编排的端口系统将 AI 代理连接到浏览器，每个端口在自动化流程中都有特定的用途。当其中一个端口停止监听时，整个链条就会断裂——您的 AI 助手突然无法与网页交互。令人沮丧的"连接被拒绝"或"地址已被使用"错误让许多开发者手足无措。

本指南提供系统化的方法来诊断和修复 OpenClaw 端口问题。无论您面对的是网关端口 18789 拒绝连接、CDP 中继 18792 无法桥接到浏览器，还是托管浏览器端口无法初始化，您都能在这里找到针对性的解决方案。我们将介绍底层架构、诊断流程图、特定平台场景，以及保持自动化可靠运行的预防措施。

## 要点速览

**更新说明（2026 年 10 月 9 日）：** 本文里的固定端口号（控制服务 18791、中继 18792、托管浏览器 18800+）对应的是 2026 年初的 OpenClaw 版本。现在的官方文档改为按配置文件分配浏览器与中继端口（包括 `cdpPort`），独立运行的扩展中继监听 `ws://127.0.0.1:<port>/extension`。请运行 `openclaw browser extension cdp` 查看你的安装实际使用的端点，并升级到 OpenClaw 2026.8.2 或更新版本，它修复了 2026 年的两个中继安全问题，详见 [OpenClaw 浏览器中继指南：Chrome 扩展配对、操作浏览器与报错排查](/zh/posts/openclaw-browser-relay-guide)。

OpenClaw 使用四个端口范围：网关（18789）、控制服务（18791）、CDP 中继（18792）和托管浏览器（18800+）。当端口无法监听时，首先运行 `openclaw status --all` 来识别哪个组件出了问题。最常见的原因是端口冲突（45%）、服务未运行（30%）和配置错误（15%）。运行 `openclaw doctor --fix` 可以自动解决大多数问题。对于端口冲突，使用 `lsof -i :18789` 来识别阻塞的进程。

## 理解 OpenClaw 端口架构

![OpenClaw 端口架构图，显示网关、控制服务、CDP 中继和托管浏览器端口](https://www.aifreeapi.com/posts/zh/openclaw-port-not-listening/img/port-architecture.png)

在深入故障排除之前，了解 OpenClaw 端口如何协同工作有助于您准确定位故障发生的位置。该系统作为多层通信管道运行，每个端口在从 AI 代理到浏览器的流程中处理特定的职责。

网关端口 18789 是所有 OpenClaw 操作的主要入口点。当您通过 Claude Code、Cursor 或任何 MCP 兼容代理运行命令时，这些请求首先到达这个 WebSocket 和 HTTP 端点。网关管理身份验证、将请求路由到适当的服务、维护会话状态，并在启用时托管控制 UI。如果此端口失败，系统中的其他任何东西都无法运行——代理无法连接，您会立即看到"连接被拒绝"错误。

端口 18791 处理控制服务，这是一个管理浏览器生命周期操作的内部 RPC 端点。此服务协调启动、停止和监控浏览器实例。当您请求新的托管浏览器会话时，网关与此服务通信以生成适当的 Chrome 进程。控制服务故障通常表现为浏览器无法启动，而不是直接的连接错误。

端口 18792 上的 CDP 中继桥接 OpenClaw 和实际浏览器实例之间的差距。在扩展中继模式下，Chrome 扩展连接到此端口以建立 CDP 命令的 WebSocket 隧道。中继对连接进行身份验证，代理 Chrome DevTools Protocol 消息，并维护浏览器自动化所需的实时通信。即使网关健康，CDP 中继问题通常也会在浏览器自动化命令失败时出现。

托管浏览器实例占用从 18800 开始的端口，每个配置文件都会获得自己的端口分配。当您为不同的自动化任务配置多个浏览器配置文件时，OpenClaw 会分配顺序端口——默认配置文件为 18800，"work"配置文件为 18801，依此类推。这些端口在 OpenClaw 和隔离的 Chrome 实例之间直接传输原生 CDP 流量。这里的问题通常表示浏览器启动失败或 Chrome 可执行文件问题。

理解这种[浏览器中继架构](/zh/posts/openclaw-browser-relay-guide)有助于您正确解释诊断输出。当 `openclaw status --all` 报告网关正在运行但 CDP 中继显示没有连接时，您就知道应该将故障排除重点放在浏览器端而不是核心服务上。同样，如果端口 18800 没有监听但 18789 工作正常，问题就具体出在托管浏览器初始化上。

所有端口默认绑定到 127.0.0.1（回环地址），这通过防止远程访问提供安全性。这种默认配置意味着 OpenClaw 只接受来自本地机器的连接。当您需要通过 Tailscale 或局域网配置进行远程访问时，会有额外的身份验证要求——这是我们将在特殊场景部分解决的常见配置错误来源。

## 快速诊断指南

![OpenClaw 端口问题分步故障排除诊断流程图](https://www.aifreeapi.com/posts/zh/openclaw-port-not-listening/img/diagnostic-flowchart.png)

面对端口问题时，系统化的诊断方法比随机故障排除尝试更节省时间。本节提供一个决策树工作流程，无论哪个端口失败，都能在几分钟内识别根本原因。

每次故障排除会话都从综合状态命令开始。运行 `openclaw status --all` 会生成一个完整的诊断报告，涵盖网关进程、所有配置的服务、端口绑定和最近的活动。这个单一命令通常无需进一步调查就能揭示确切的问题。输出清楚地指示服务是否正在运行、哪些端口正在监听，以及任何可能解释故障的配置警告。

如果状态命令显示网关为"未运行"或报告端口 18789 上没有进程监听，您就识别出了服务启动失败。最常见的原因包括配置错误、权限问题或先前安装的残留进程。在尝试启动服务之前，在 macOS 和 Linux 上使用 `lsof -nP -iTCP:18789 -sTCP:LISTEN` 检查现有的监听者。此命令会显示是否有其他进程占用了该端口。

当其他东西占用网关端口时，您会看到显示进程名称和 ID 的输出。常见的罪魁祸首包括迁移期间未正确删除的旧 ClawdBot 安装、转发到同一端口的 SSH 隧道，或来自崩溃会话的重复 OpenClaw 实例。识别阻塞进程决定了您的下一步——要么终止不需要的进程，要么重新配置端口分配以避免冲突。

对于服务报告正在运行但连接仍然失败的情况，问题通常在于绑定模式配置。`openclaw gateway status` 命令提供有关网关如何绑定到网络接口的详细信息。如果您看到"bind=tailnet but no tailnet interface found"，说明 OpenClaw 尝试使用机器上不存在的 Tailscale IP 地址。同样，"bind=lan"要求指定的网络接口可用且正确配置。

`openclaw doctor` 命令是常见问题的自动修复工具。运行 `openclaw doctor --fix` 会尝试纠正配置问题、修复权限、创建缺失的目录并迁移过时的设置。此命令无需手动干预即可解决大约 60% 的端口问题。在深入手动故障排除之前，请始终先运行它。

当自动化工具无法解决问题时，检查日志可提供关键的上下文。网关日志位于不同的位置，具体取决于您的平台：临时日志在 `/tmp/openclaw/openclaw-YYYY-MM-DD.log`，macOS 上在 `~/.openclaw/logs/gateway.log`，使用 systemd 的 Linux 系统上使用 `journalctl --user -u openclaw-gateway.service -n 200 --no-pager`。这些日志包含启动错误、身份验证失败和详细的错误消息，可以精确定位配置问题。

对于经过上述诊断仍然存在的持久问题，终极选项涉及停止所有 OpenClaw 进程、清除状态并重新初始化。运行 `openclaw gateway stop` 停止服务，删除 `$OPENCLAW_STATE_DIR`（通常为 `~/.openclaw`）的内容，然后依次运行 `openclaw channels login` 和 `openclaw gateway restart` 重新启动。这种清空状态的方法可以解决崩溃或升级失败后可能发生的状态损坏问题。

## 修复网关端口（18789）问题

网关端口比其他端口更频繁地遇到问题，因为它处理主要的连接点并且具有最复杂的配置选项。了解特定的故障模式有助于您应用针对性的修复，而不是通用的故障排除。

端口冲突是最常见的网关问题，占所有端口相关支持请求的近一半。当另一个进程占用端口 18789 时，OpenClaw 无法启动其网关服务。在 macOS 和 Linux 上，诊断命令 `lsof -nP -iTCP:18789 -sTCP:LISTEN` 可以揭示阻塞的进程。在 Windows 上，使用 `netstat -ano | findstr :18789` 来识别进程 ID，然后使用 `tasklist /FI "PID eq [PID]"` 来确定进程名称。

一旦识别了冲突的进程，决定是终止它还是重新配置 OpenClaw 使用不同的端口。对于不需要的进程，如残留的 ClawdBot 实例，终止是有意义的。在 Unix 系统上使用 `kill -9 [PID]`，在 Windows 上使用 `taskkill /F /PID [PID]`。但是，如果该进程有合法用途——比如您配置的 SSH 隧道——考虑在配置中更改 OpenClaw 的网关端口。

服务启动失败发生在网关进程在初始化期间崩溃时。常见原因包括无效的配置文件、缺少 API 密钥和权限问题。网关需要通过环境变量或配置文件配置有效的 Anthropic API 密钥。运行 `openclaw doctor` 可以检查这些先决条件并报告任何缺失的要求。

配置文件损坏可能导致启动失败而没有明显的错误消息。主配置文件在大多数系统上位于 `~/.openclaw/config.json`。如果您怀疑损坏，请重命名现有文件并让 OpenClaw 创建新的默认配置。然后您可以手动迁移特定设置，在每次更改后测试启动以识别有问题的选项。

绑定模式不匹配会导致微妙的故障，服务启动但拒绝来自预期来源的连接。网关支持多种绑定模式：`loopback`（仅 127.0.0.1）、`lan`（本地网络接口）、`tailnet`（Tailscale 接口）和 `custom`（指定地址）。每种非回环模式都需要额外的配置。对于 `tailnet` 模式，Tailscale 必须在网关启动之前运行并连接。对于 `lan` 模式，在配置中指定正确的接口名称。

身份验证要求会在非回环绑定时生效。当网关绑定到 127.0.0.1 以外的地址时，它会强制要求基于令牌的身份验证以防止未经授权的访问。将 `gateway.auth.mode` 设置为 `token` 或 `password` 并配置相应的凭据。如果没有正确的身份验证设置，连接到非回环地址的客户端会收到 401 未授权错误，尽管端口是可用的。

防火墙和安全软件偶尔会阻止网关端口，即使是回环连接也是如此。macOS 用户在第一次启动 OpenClaw 时可能会遇到 Gatekeeper 提示。Linux 防火墙规则（iptables、ufw、firewalld）可能会阻止连接。在 Windows 上，Windows Defender 防火墙可能需要明确的例外。如果尽管端口显示为正在监听但连接失败，请暂时禁用安全软件以测试它是否在阻止访问。

特定平台的服务管理增加了另一层复杂性。在 macOS 上，OpenClaw 注册一个 launchd 作业来管理网关生命周期。该作业位于 `~/Library/LaunchAgents/com.openclaw.gateway.plist`。如果此 plist 损坏或包含过时的路径，服务将无法正确启动。运行 `launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist` 后再运行 `openclaw gateway install` 可以使用正确的设置重新创建启动代理。

使用 systemd 的 Linux 系统通过用户服务管理网关。使用 `systemctl --user status openclaw-gateway.service` 检查状态。如果服务显示为失败，请使用 `journalctl --user -u openclaw-gateway.service -n 50` 检查日志以获取特定的错误消息。常见问题包括 systemd 环境中 PATH 中缺少 Node.js 或服务文件中的工作目录规范不正确。

Windows 用户面临独特的挑战，因为 OpenClaw 作为计划任务而不是传统服务运行。在任务计划程序的"OpenClaw"文件夹下检查任务状态，或从命令提示符使用 `schtasks /Query /TN "OpenClaw Gateway" /V`。失败的任务通常是由于用户权限更改或移动了可执行文件位置的更新造成的。以管理员身份运行后使用 `openclaw gateway install` 重新注册任务通常可以解决 Windows 特定的启动失败。

环境变量冲突可能会在所有平台上破坏网关启动。如果您有来自先前配置的 `OPENCLAW_GATEWAY_PORT` 或类似的环境变量设置，它们会覆盖配置文件设置。检查您的 shell 配置文件（`.bashrc`、`.zshrc`、PowerShell 配置文件）是否存在冲突的导出。`openclaw status --all` 输出包含环境变量信息，有助于识别此类冲突。

内存和资源限制会导致资源受限环境中的启动失败。网关及其托管浏览器需要可用内存才能运行。在 RAM 有限的系统上——特别是开发容器或小型虚拟机——网关可能无法启动或在启动后不久崩溃。在启动期间使用 `htop` 或活动监视器监控系统内存。考虑增加可用资源或减少并发托管浏览器配置文件的数量。

## 解决控制服务（18791）问题

端口 18791 上的控制服务处理浏览器生命周期管理的内部通信。与网关不同，用户不直接连接到此端口——它充当 OpenClaw 组件之间的内部 RPC 端点。这里的问题通常表现为浏览器无法启动或停止，而不是直接的连接错误。

控制服务故障通常与网关问题有相同的根本原因，因为两个服务都由同一个监督进程管理。当网关显示健康但浏览器命令失败时，请检查 `openclaw status --all` 输出中控制服务的特定状态行，以确认它是否确实在运行。

监督进程管理网关和控制服务。如果您看到网关正在运行但控制服务离线，监督进程可能在启动辅助服务时遇到了错误。检查 `~/.openclaw/logs/supervisor.log` 中与控制服务相关的特定错误消息。

在极少数情况下，控制服务端口可能独立于网关遇到冲突。当其他软件巧合地使用端口 18791 时，就会发生这种情况。诊断方法与网关故障排除相同：使用 `lsof -i :18791` 检查竞争进程，然后终止它们或重新配置冲突的软件。

控制服务与网关之间的通信故障表示内部状态问题。运行 `openclaw gateway stop` 后再运行 `openclaw gateway restart` 可以清除内部状态并重新初始化服务之间的通信通道。这可以解决大多数服务间通信问题，而无需更改配置。

当管理许多浏览器实例时，资源耗尽可能会独立影响控制服务。每个托管浏览器都会消耗系统资源，而控制服务会跟踪所有这些资源。如果您运行许多并行浏览器自动化任务，控制服务可能难以跟上。在自动化代码中减少并发或实现请求队列以防止服务过载。

控制服务还处理浏览器配置文件管理，包括创建新配置文件和清理旧配置文件。如果配置文件目录损坏或过大，服务在尝试使用它们时可能会变慢或失败。定期清理浏览器配置文件目录（`~/.openclaw/browsers/`）可以删除可能影响性能的累积数据。保留您积极使用的配置文件，但删除已累积的实验性或测试配置文件。

## 故障排除 CDP 中继（18792）

CDP 中继端口桥接 OpenClaw 到浏览器实例，使其对于允许控制现有 Chrome 会话的扩展中继模式至关重要。当此端口失败时，即使网关看起来健康，浏览器自动化命令也会超时或返回连接错误。

扩展连接问题是主要的 CDP 中继故障模式。在扩展中继模式下，OpenClaw Chrome 扩展维护到端口 18792 的 WebSocket 连接。如果扩展未安装、已禁用或无法到达中继，浏览器命令将失败。通过检查 Chrome 的扩展管理页面（chrome://extensions）并确认 OpenClaw 已启用来验证扩展状态。

扩展需要在连接到 CDP 中继之前与网关进行明确的配对。如果您最近重新安装了 OpenClaw 或清除了配置，配对可能会丢失。打开扩展弹出窗口并检查连接状态。如果显示"已断开连接"或"需要配对"，请完成配对流程以重新建立连接。

扩展和中继之间的 WebSocket 连接可能由于浏览器安全策略而失败。Chrome 强制执行的内容安全策略限制可能会在某些上下文中阻止 WebSocket 连接。尝试从简单的网页而不是扩展页面或 chrome:// URL 连接，以排除 CSP 作为原因。

多个浏览器配置文件或 Chrome 安装可能会导致关于哪个浏览器应该连接到中继的混淆。扩展只在安装它的 Chrome 配置文件中起作用。如果您在多个配置文件中工作，请确保扩展已在您需要自动化的每个配置文件中安装和配置。

CDP 中继身份验证失败发生在中继和网关具有不匹配的身份验证状态时。在影响身份验证的配置更改后，两个组件都需要使用匹配的凭据重新初始化。`openclaw gateway restart` 命令确保两个服务都以一致的身份验证配置启动。

对于专门调试 CDP 中继，在尝试浏览器连接之前使用 `openclaw gateway --verbose` 启用详细日志记录。详细输出显示 WebSocket 连接尝试、身份验证握手和 CDP 消息路由——这些信息对于识别通信中断的确切位置非常有价值。

## 托管浏览器端口（18800+）修复

托管浏览器端口在 OpenClaw 和它控制的隔离 Chrome 实例之间传输原生 Chrome DevTools Protocol 流量。每个配置的浏览器配置文件都会获得一个从 18800 开始的专用端口。当这些端口无法监听时，底层 Chrome 实例没有正确启动。

浏览器可执行文件路径问题导致最多的托管浏览器故障。OpenClaw 需要知道 Chrome 安装在哪里才能启动托管实例。配置选项 `browser.executablePath` 指定此位置。常见路径包括 Linux 上的 `/usr/bin/google-chrome-stable`、macOS 上的 `/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`，以及 Windows 上的 `C:\Program Files\Google\Chrome\Application\chrome.exe`。如果 Chrome 被移动或以非标准方式安装，请更新此路径。

Linux 上的 Snap 和 Flatpak Chrome 安装会导致 CDP 初始化失败，因为这些沙盒包格式限制了 Chrome 打开调试端口的能力。解决方案是通过传统包管理器（apt、yum）而不是作为 snap 安装 Chrome。使用 `snap remove chromium` 删除 snap 版本，并直接从官方仓库安装 Google Chrome。

Chrome 配置文件损坏可能会阻止托管实例启动。OpenClaw 为托管浏览器维护单独的配置文件目录，通常在 `~/.openclaw/browsers/` 下。如果配置文件损坏——可能是由于先前的崩溃——Chrome 将无法初始化。重命名或删除有问题的配置文件目录允许 OpenClaw 在下次启动时创建新的配置文件。

CDP 端口可用性影响托管浏览器启动。每个配置文件在 Chrome 启动时都需要其分配的端口是空闲的。如果其他东西占用端口 18800，默认托管浏览器将无法启动。使用 `lsof -i :18800` 检查冲突，并像解决网关端口冲突一样解决它们。

多个托管浏览器配置文件需要仔细的端口管理。配置指定每个配置文件使用哪个端口：

```json
{
  "browserProfiles": {
    "openclaw": { "cdpPort": 18800 },
    "work": { "cdpPort": 18801 },
    "test": { "cdpPort": 18802 }
  }
}
```

确保这些分配的端口与系统上的其他服务之间没有冲突。还要验证您的防火墙允许连接到您配置的整个端口范围。

Chrome 启动标志影响 CDP 可访问性。托管浏览器使用启用远程调试的特定标志启动。来自浏览器策略的冲突标志（在企业环境中很常见）可能会覆盖这些设置。检查您的组织是否应用了可能干扰调试功能的 Chrome 策略。

GPU 加速问题可能会阻止托管浏览器在无头服务器或没有 GPU 支持的虚拟机中正确启动。Chrome 默认尝试使用硬件加速，这在这些环境中会失败。通过在配置中的浏览器启动参数中添加 `--disable-gpu` 来配置托管浏览器使用软件渲染。这以一些渲染性能换取无 GPU 环境中的可靠性。

临时目录问题会影响托管浏览器启动，因为 Chrome 在初始化期间会将数据写入临时位置。如果 `/tmp` 已满、以只读方式挂载或具有限制性权限，Chrome 将无法启动。使用 `df -h /tmp` 验证临时目录可用性，使用 `ls -la /tmp` 验证权限。在临时目录较小或受限的系统上，在启动 OpenClaw 之前通过 `TMPDIR` 环境变量配置备用临时位置。

配置文件锁定冲突发生在尝试从多个 OpenClaw 实例使用相同的托管浏览器配置文件时。Chrome 在配置文件目录中创建锁定文件以防止并发访问。如果先前的实例崩溃而没有释放锁定，新实例将无法使用该配置文件。手动删除配置文件目录中的 `SingletonLock` 和 `SingletonCookie` 文件可以允许访问，但请确保没有其他进程实际上正在使用该配置文件以避免数据损坏。

## 特殊场景和边缘情况

除了上面介绍的端口特定问题外，还有几种场景会创建值得专门关注的独特故障排除挑战。

ClawdBot 到 OpenClaw 的迁移让许多用户留下了持续的冲突。升级过程并不总是干净地删除先前的安装，导致新旧服务竞争端口 18789。完整的迁移需要停止 ClawdBot 服务、卸载旧包并删除遗留配置文件。在使用 systemd 的系统上，还要删除 `~/.config/systemd/user/clawdbot-gateway.service` 中的旧服务文件，并使用 `systemctl --user daemon-reload` 重新加载守护进程。

清理过程涉及几个步骤：首先 `systemctl --user stop clawdbot-gateway.service`（如果存在），然后 `pkill -f clawdbot` 终止任何剩余进程，接着 `npm uninstall -g clawdbot` 删除包。最后，在尝试启动 OpenClaw 之前，使用 `ps aux | grep clawdbot` 验证没有 clawdbot 进程残留。

Docker 部署需要在容器配置中显式进行端口映射。docker-compose.yml 必须暴露所有必要的端口：

```yaml
ports:
  - "18789:18789"  # 网关
  - "18791:18791"  # 控制服务
  - "18792:18792"  # CDP 中继
  - "18800-18810:18800-18810"  # 托管浏览器
```

Docker 的网络模型意味着网关必须绑定到 0.0.0.0 而不是 127.0.0.1 才能接受来自容器外部的连接。这需要配置 `gateway.bind: lan` 以及适当的身份验证，因为非回环绑定强制要求认证。

平台即服务部署（Zeabur、Railway 等）引入了额外的约束。这些平台通常要求服务绑定到特定地址并在指定端口上执行健康检查。如果 OpenClaw 绑定到回环，期望从网关端口获得响应的健康探测将失败。根据您平台的要求进行配置，通常涉及 `gateway.bind: lan` 或 `custom` 以及平台指定的地址。

Tailscale 集成失败发生在网关配置为 `tailnet` 绑定但 Tailscale 守护进程未运行或未分配 IP 地址时。Tailscale 必须在网关启动之前经过身份验证并连接。使用 `tailscale status` 验证 Tailscale 状态，并确保它显示 100.x.x.x IP 地址。如果 Tailscale 在单独的机器上运行，请将 OpenClaw 配置为绑定到 `loopback`，并使用 Tailscale Serve 或 Funnel 来对外暴露网关。

模式切换冲突发生在本地和远程连接模式之间切换时。macOS 应用程序特别容易受到竞态条件的影响，在切换到远程模式时本地网关 launchd 作业没有正确卸载。SSH 隧道然后绑定到端口 18789，但本地网关不断尝试重启并失败。手动干预需要在模式切换之前卸载启动代理：`launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist`。

[安装指南](/zh/posts/openclaw-installation-guide)详细介绍了初始设置，但安装后的更改可能会创建不一致的状态。如果您修改了安装路径、Node.js 版本或系统用户，服务定义可能会引用过时的位置。使用 `openclaw gateway install` 重新安装服务组件会更新所有系统集成点以匹配当前设置。

## 错误消息参考

![常见 OpenClaw 错误消息及其解决方案的快速参考表](https://www.aifreeapi.com/posts/zh/openclaw-port-not-listening/img/error-solutions.png)

故障排除时，确切知道每个错误消息的含义可以加速诊断。此参考表将常见错误映射到其原因和解决方案。

错误"Address already in use: 127.0.0.1:18789"表示端口冲突，另一个进程占用了网关端口。运行 `lsof -i :18789` 识别该进程，然后终止它或将 OpenClaw 配置为使用不同的端口。

"Gateway failed to start"出现在网关进程在初始化期间崩溃时。首先运行 `openclaw doctor --fix` 解决常见配置问题。如果这不起作用，请检查 `~/.openclaw/logs/gateway.log` 以获取特定的启动错误。

"bind=tailnet but no tailnet interface found"意味着 OpenClaw 尝试使用 Tailscale 网络，但没有可用的 Tailscale IP。要么使用 `tailscale up` 启动 Tailscale，要么在配置中将绑定模式更改为 `loopback`。

"Connection refused: 127.0.0.1:18789"表示网关根本没有运行。使用 `openclaw gateway restart` 启动它，或检查系统服务状态以了解它为什么可能已停止。

"401 Unauthorized: invalid gateway token"出现在身份验证凭据不匹配时。对于非回环绑定，请验证配置中的 `gateway.auth.token` 与客户端提供的内容匹配。

"Browser executable not found"意味着 Chrome 不在预期路径上。更新配置中的 `browser.executablePath` 以指向实际的 Chrome 安装位置。

"Another gateway instance is already listening"通常表示 ClawdBot 迁移冲突。使用 `pkill -f clawdbot` 和 `npm uninstall -g clawdbot` 清理旧安装。

"CDP initialization failed"通常源于 Linux 上的 Snap 打包 Chrome。通过 apt 而不是 snap 安装 Chrome 以解决兼容性问题。

"ENOSPC: no space left on device"表示磁盘空间问题，阻止 OpenClaw 写入配置或日志。释放磁盘空间并重启网关。

"pairing required (1008)"意味着连接的设备尚未获得批准。运行 `openclaw devices list` 查看待处理的请求，使用 `openclaw devices approve [ID]` 授权。

## 预防和维护

预防端口问题比反复故障排除更高效。建立定期维护实践并了解配置最佳实践可以保持您的 OpenClaw 安装可靠运行。

定期健康检查可以在问题导致故障之前发现它们。每天在自动化脚本中运行 `openclaw health --verbose` 以验证所有组件是否正常运行。此命令检查网关可达性、服务状态和配置有效性。将输出导入日志文件以进行历史跟踪，或与可以在故障时发出警报的监控系统集成。

在系统重启之前，确保 OpenClaw 干净地关闭。在重启机器之前运行 `openclaw gateway stop` 可以防止由于不完整写入而损坏的状态。在 OpenClaw 作为服务运行的系统上，将其配置为关机脚本。干净的关闭大大减少了重启后配置问题的频率。

保持您的 OpenClaw 安装更新以受益于错误修复和兼容性改进。开发团队定期解决用户报告的端口相关问题。使用 `npm outdated -g @anthropics/openclaw` 检查更新，使用 `npm update -g @anthropics/openclaw` 升级。更新后，运行 `openclaw doctor` 以确保配置与新版本兼容。

监控日志文件大小以防止磁盘空间问题。在大量使用下，网关日志可能会变得很大。通过操作系统的 logrotate 工具配置日志轮换，或定期归档和清除旧日志文件。运行 `find ~/.openclaw/logs -name "*.log" -mtime +7 -delete` 的 cron 作业可以删除超过一周的日志。

在进行更改之前备份您的配置。`~/.openclaw/config.json` 文件包含您的所有自定义设置。在尝试设置之前将其复制到备份位置。如果更改引入问题而不是解决问题，这允许快速恢复。

记录您的工作配置，特别是在团队环境中。当多个开发人员使用 OpenClaw 时，拥有记录的标准配置可以防止每个人都对相同的问题进行故障排除。共享工作的浏览器配置文件配置、身份验证设置以及您的环境需要的任何平台特定调整。

在生产环境中部署 OpenClaw 时，实施适当的服务监控。使用进程监督器如 systemd（Linux）或 launchd（macOS），配置为在故障时重启网关。设置合理的重启限制以防止持续错误时的无限重启循环——三次尝试并逐渐增加延迟对于瞬态故障效果良好，同时在基本配置问题上快速停止。

在容器化部署中启动前测试端口可用性。添加预启动检查以验证端口 18789-18810 可用可以防止容器启动但 OpenClaw 无法绑定到所需端口的静默故障。这在 Kubernetes 等编排系统中特别重要，端口冲突可能表示调度问题。

对于 [MCP 协议集成](/zh/topics/claude)，确保您的 AI 代理配置指向正确的网关地址。代理配置中不匹配的地址会导致看起来像端口问题但实际上源于错误的客户端设置的连接失败。验证地址和任何身份验证令牌都与网关期望的内容匹配。

## 常见问题

了解关于 OpenClaw 端口问题的常见问题有助于解决可能不适合上述故障排除类别的问题。这些问题来自社区论坛、GitHub 问题和支持渠道。

**OpenClaw 默认使用什么端口？**

OpenClaw 使用端口 18789 作为代理连接的主要网关端口。这个单一端口处理来自 Claude Code 和 Cursor 等 AI 代理的 WebSocket 连接、控制 UI 的 HTTP 请求以及程序化交互的 API 调用。其他端口包括用于内部控制服务的 18791、用于桥接浏览器扩展的 CDP 中继的 18792，以及用于托管浏览器实例的 18800 及以上端口。所有端口默认绑定到 localhost（127.0.0.1），这意味着除非明确配置，否则它们只接受本地连接。

**如何检查 OpenClaw 端口是否正在监听？**

最快的方法是使用 `openclaw status --all` 命令，它会报告所有 OpenClaw 服务及其端口绑定的状态。对于较低级别的验证，在 macOS 或 Linux 上使用 `lsof -nP -iTCP:18789 -sTCP:LISTEN` 检查特定端口。此命令显示是否有东西在监听以及哪个进程拥有该端口。在 Windows 上，使用 `netstat -ano | findstr :18789` 可以达到相同的效果。输出有助于区分"端口未监听"（服务未运行）和"端口被占用"（不同进程拥有它）场景。

**我可以更改默认的 OpenClaw 端口吗？**

是的，您可以通过 `~/.openclaw/config.json` 配置文件将 OpenClaw 配置为使用不同的端口。为主网关设置 `gateway.port` 为您所需的端口号，并为托管浏览器端口调整 `browserProfiles.[name].cdpPort`。更改端口后，使用 `openclaw gateway restart` 重启网关。请记住更新连接到 OpenClaw 的任何代理配置以使用新的端口号。当默认端口与系统上的其他服务冲突时，端口更改很有用。

**为什么 OpenClaw 在崩溃后显示"address already in use"？**

当 OpenClaw 崩溃而没有干净地关闭时，操作系统可能不会立即释放端口绑定。这种 TIME_WAIT 状态通常持续 30-60 秒。如果您立即尝试重启，您会看到"address already in use"错误。等待一分钟后重试，或使用 `lsof -i :18789` 验证旧进程是否已完全终止。在 Linux 上，您还可以使用 `ss -tlnp | grep 18789` 检查。如果旧进程持续存在，请在重启之前使用 `kill -9 [PID]` 强制终止。

**如何在不同的机器上运行 OpenClaw 并连接到它？**

在远程机器上运行 OpenClaw 需要配置非回环绑定和身份验证。设置 `gateway.bind: lan` 或 `gateway.bind: custom` 以及您服务器的 IP 地址。非回环绑定需要身份验证，因此配置 `gateway.auth.mode: token` 并在 `gateway.auth.token` 中设置强令牌。从客户端机器连接时，在代理配置中指定远程地址和令牌。对于安全的远程访问，考虑使用 Tailscale，它提供加密的点对点连接。使用 Tailscale，设置 `gateway.bind: tailnet`，OpenClaw 会自动绑定到您的 Tailscale IP。

**"connection refused"和"connection timed out"错误有什么区别？**

这些错误表示不同的故障模式。"Connection refused"意味着操作系统主动拒绝了连接，因为该端口上没有任何东西在监听。这发生在 OpenClaw 服务未运行或崩溃时。"Connection timed out"意味着连接尝试在超时期限内没有收到响应。这通常表示防火墙阻塞、IP 地址不正确或客户端和服务器之间的网络连接问题。对于被拒绝的连接，专注于启动服务。对于超时，调查客户端和服务器之间的网络路径和防火墙配置。

**如何在 Docker 容器中故障排除 OpenClaw？**

Docker 网络增加了复杂性，因为容器具有隔离的网络命名空间。首先，确保 docker-compose.yml 中的端口映射正确——您需要端口 18789-18810（或您配置的范围）的显式映射。网关必须绑定到容器内的 0.0.0.0 以接受来自外部的连接，这需要 `gateway.bind: lan` 和适当的身份验证。使用 `docker compose logs openclaw-gateway` 查看服务日志。如果网关启动但代理无法连接，请验证您正在连接到主机暴露的端口，而不是容器的内部地址。

**OpenClaw 是否适用于 Brave、Edge 或其他 Chromium 浏览器？**

是的，OpenClaw 适用于扩展中继模式的任何基于 Chromium 的浏览器，因为 Chrome 扩展与 Brave、Edge、Vivaldi 和类似浏览器兼容。对于托管浏览器实例，将 `browser.executablePath` 配置为指向您首选浏览器的可执行文件。请注意，托管浏览器模式在指定的浏览器中创建隔离的配置文件，因此您将拥有一个专门用于自动化的单独浏览器实例，而不是使用您的常规浏览配置文件。

## 结论

OpenClaw 端口问题虽然令人沮丧，但遵循可预测的模式，系统化的故障排除可以有效地解决。了解四端口架构——网关（18789）、控制服务（18791）、CDP 中继（18792）和托管浏览器（18800+）——为针对性诊断提供基础。每次故障排除会话都从 `openclaw status --all` 和 `openclaw doctor --fix` 开始，可以解决大多数问题而无需深入调查。

对于持久问题，诊断流程图指导您识别根本原因：端口冲突、服务故障、绑定配置错误和身份验证问题各有特定的解决方案。macOS launchd、Linux systemd、Docker 网络和 Windows 服务的平台特定注意事项需要了解，但遵循一致的原则。

通过定期健康检查、干净关闭和配置备份进行预防提供了最有效的端口可靠性方法。当问题确实发生时，错误消息参考表通过将特定消息映射到其原因和解决方案来加速诊断。

有了本指南的系统方法，您可以维持可靠的 OpenClaw 运行并在问题出现时快速恢复。理解端口架构的投资在每次需要故障排除时都会获得回报——将令人沮丧的调试会话转变为快速、针对性的修复。