独立的开发环境，不影响主 Gateway：

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
​

Dev 模式使用隔离的状态/配置目录，默认端口 19001。

gateway.reload 和 gateway.remote 是例外——修改它们不会触发重启。

OpenClaw 读取环境变量的优先级：

1. 父进程传入的环境变量
2. 当前工作目录的 .env 文件
3. ~/.openclaw/.env（全局兜底）

.env 文件不会覆盖已有的环境变量。你也可以在配置文件中内联设置：

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
​

如果 Gateway 运行在 systemd/launchd 下，建议把 API Key 放在 ~/.openclaw/.env 中，确保守护进程能读取。

控制面板写操作（config.apply、config.patch、update.run）有速率限制：每 60 秒最多 3 次请求（按 deviceId + clientIp 计算）。超限时返回 UNAVAILABLE 和 retryAfterMs。

推荐起步配置：

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}
​

多平台配置：

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["123456789012345678"] },
    },
  },
}
​

纯本地模型：

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.5-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.5-gs32",
            name: "MiniMax M2.5 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}
​

更多配置模板见附录 G 配置文件详解。

对于生产环境，OpenClaw 支持 SecretRef——不需要把密钥明文写在配置文件中。支持三种来源：

环境变量引用：

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
​

文件引用：

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
​

外部命令引用（支持 1Password、HashiCorp Vault、sops 等）：

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }
​

配置密钥提供者：

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
  },
}
​

密钥管理命令：

openclaw secrets audit --check    # 检查明文密钥
openclaw secrets configure        # 交互式配置 SecretRef
openclaw secrets reload           # 刷新密钥快照
​

SecretRef 解析是启动时一次性完成的（不是每次请求时），解析失败会阻止 Gateway 启动。运行时使用内存中的快照，避免密钥提供者故障影响请求路径。

1Password 集成示例：

{
  secrets: {
    providers: {
      onepassword_openai: {
        source: "exec",
        command: "/opt/homebrew/bin/op",
        allowSymlinkCommand: true,
        trustedDirs: ["/opt/homebrew"],
        args: ["read", "op://Personal/OpenClaw QA API Key/password"],
        passEnv: ["HOME"],
        jsonOnly: false,
      },
    },
  },
  models: {
    providers: {
      openai: {
        baseUrl: "https://api.openai.com/v1",
        models: [{ id: "gpt-5", name: "gpt-5" }],
        apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
      },
    },
  },
}
​

如果 OpenClaw 运行在身份感知代理（Pomerium、Caddy + OAuth、nginx + oauth2-proxy）后面，可以使用 trusted-proxy 模式：

{
  gateway: {
    bind: "loopback",
    trustedProxies: ["10.0.0.1"],
    auth: {
      mode: "trusted-proxy",
      trustedProxy: {
        userHeader: "x-forwarded-user",
        allowUsers: ["nick@example.com"],
      },
    },
  },
}
​

nginx + oauth2-proxy 示例：

location / {
    auth_request /oauth2/auth;
    auth_request_set $user $upstream_http_x_auth_request_email;

    proxy_pass http://openclaw:18789;
    proxy_set_header X-Auth-Request-Email $user;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}
​

安全警告：此模式将认证完全委托给代理。必须确保：代理是唯一入口、trustedProxies 最小化、代理会覆盖（而非追加）转发头。启用后 openclaw security audit 会标记为 critical——这是故意的提醒。

定期运行安全审计（特别是修改配置或暴露网络后）：

openclaw security audit           # 基本审计
openclaw security audit --deep    # 深度审计
openclaw security audit --fix     # 自动修复
​

它会检查：Gateway 认证暴露、浏览器控制暴露、提权 allowlist、文件权限等常见问题。

核心安全原则：OpenClaw 采用个人助理信任模型——每个 Gateway 一个可信操作者。它不是敌对多租户安全边界。如果需要多用户隔离，应分开 Gateway + 凭证（最好分开操作系统用户/主机）。

{
  logging: {
    level: "info",           // 文件日志级别
    consoleLevel: "info",    // 控制台日志级别
    consoleStyle: "pretty",  // pretty | compact | json
    redactSensitive: "tools",
  },
}
​

1. 可选更新（git 安装时可选拉取最新代码）
2. UI 协议刷新（Protocol Schema 更新时重建控制面板 UI）
3. 健康检查 + 重启提示
4. 技能状态摘要（可用/缺失/阻塞）
5. 配置规范化（遗留值格式迁移）
6. OpenCode 提供商覆盖警告
7. 遗留磁盘布局迁移（会话、Agent 目录、WhatsApp 认证）
8. 遗留 Cron 存储迁移
9. 状态完整性检查（目录缺失、权限、云同步警告）
10. 模型认证健康（OAuth 过期、冷却/禁用状态）
11. Hooks 模型验证
12. 沙箱镜像修复
13. Gateway 服务迁移和清理
14. 安全警告
15. systemd linger 检查（Linux）
16. 技能状态
17. Gateway 认证检查
18. 运行时与端口诊断
19. 运行时最佳实践（Node vs Bun 检查）

活跃时段（避免深夜打扰）：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
        activeHours: {
          start: "09:00",
          end: "22:00",
          timezone: "Asia/Shanghai",
        },
      },
    },
  },
}
​

多 Agent 独立心跳：

{
  agents: {
    defaults: {
      heartbeat: { every: "30m", target: "last" },
    },
    list: [
      { id: "main", default: true },
      {
        id: "ops",
        heartbeat: {
          every: "1h",
          target: "telegram",
          to: "12345678",
          prompt: "检查服务器状态，如果一切正常回复 HEARTBEAT_OK。",
        },
      },
    ],
  },
}
​

可见性控制（按渠道定制）：

• showOk: false（默认）：静默吞掉 HEARTBEAT_OK
• showAlerts: true（默认）：发送告警内容
• useIndicator: true（默认）：发出指示器事件

手动触发心跳：

openclaw system event --text "检查紧急跟进事项" --mode now
​

轻量上下文模式：

设置 lightContext: true 让心跳只注入 HEARTBEAT.md，减少上下文大小和 Token 消耗。

推理过程透传：

设置 includeReasoning: true 额外发送 Reasoning: 前缀的推理过程消息，方便了解龙虾为什么决定通知你。建议在群聊中关闭此选项。

工具策略支持 group:* 分组写法：

{
  tools: {
    sandbox: {
      tools: {
        allow: ["group:runtime", "group:fs", "group:sessions", "group:memory"],
      },
    },
  },
}
​

可用分组：

默认镜像：openclaw-sandbox:bookworm-slim

# 构建基础沙箱镜像
scripts/sandbox-setup.sh

# 构建功能更全的镜像（含 curl、jq、nodejs、python3、git）
scripts/sandbox-common-setup.sh

# 构建沙箱浏览器镜像
scripts/sandbox-browser-setup.sh
​

默认沙箱容器没有网络访问。如需网络，设置 agents.defaults.sandbox.docker.network。

自定义绑定挂载：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          binds: ["/home/user/source:/source:ro", "/var/data/myapp:/data:ro"],
        },
      },
    },
  },
}
​

安全注意：绑定挂载会穿透沙箱文件系统。OpenClaw 会阻止危险的绑定源（如 docker.sock、/etc、/proc、/sys）。敏感挂载建议使用 :ro。

容器内一次性初始化（setupCommand）：

{
  agents: {
    defaults: {
      sandbox: {
        docker: {
          setupCommand: "apt-get update && apt-get install -y curl jq",
          network: "bridge",        // 安装包需要网络
          readOnlyRoot: false,      // 安装包需要写权限
          user: "0:0",             // 安装包需要 root
        },
      },
    },
  },
}
​

Gateway 可以通过 Bonjour 在局域网内广播自己的 WebSocket 端点，方便客户端自动发现：

• 服务类型：_openclaw-gw._tcp
• TXT 记录包含端口、TLS 状态、Tailnet DNS 等提示信息

Bonjour 限制：仅限同一局域网，不跨网络。跨网络请使用 Tailscale 或 SSH。

调试命令（macOS）：

dns-sd -B _openclaw-gw._tcp local.    # 浏览实例
dns-sd -L "<实例名>" _openclaw-gw._tcp local.  # 解析详情
​

跨网络 Bonjour（Wide-Area DNS-SD over Tailscale）：

如果节点和 Gateway 在不同网络，可以通过 Tailscale 配合 unicast DNS-SD 实现跨网络发现：

{
  gateway: { bind: "tailnet" },
  discovery: { wideArea: { enabled: true } },
}
​

一次性 DNS 服务器设置：openclaw dns setup --apply

禁用广播：设置环境变量 OPENCLAW_DISABLE_BONJOUR=1。

大多数场景只需一个 Gateway。如果需要严格隔离或冗余（比如救援 Bot），可以运行多个 Gateway。

每个实例必须唯一的配置：

• gateway.port（或 --port）
• OPENCLAW_CONFIG_PATH
• OPENCLAW_STATE_DIR
• agents.defaults.workspace

推荐使用 Profile 隔离：

# 主 Gateway
openclaw --profile main gateway --port 18789

# 救援 Gateway
openclaw --profile rescue gateway --port 19001

# 分别安装为系统服务
openclaw --profile main gateway install
openclaw --profile rescue gateway install

# 分别检查状态
openclaw --profile main status
openclaw --profile rescue status
​

端口间距建议：至少间隔 20 个端口，避免派生端口（浏览器 CDP 等）冲突。

Gateway 使用 TCP 端口绑定作为锁——同一端口只能运行一个实例。

• 如果端口被占用，启动时抛出 GatewayLockError
• 进程退出（包括崩溃和 SIGKILL）时，操作系统自动释放端口
• 不需要额外的锁文件或清理步骤

如果端口被其他进程占用，使用 openclaw gateway --port <其他端口> 或 --force 强制释放。

8. HTTP API 端点

Gateway 可以提供 HTTP API 端点，默认关闭，需手动启用。

安全警告：HTTP 端点 = 完整操作者权限。不要暴露在公网，仅限 loopback / Tailnet / 私有网络。

OpenAI Chat Completions 兼容端点

{
  gateway: {
    http: { endpoints: { chatCompletions: { enabled: true } } },
  },
}
​

curl -sS http://127.0.0.1:18789/v1/chat/completions \
  -H 'Authorization: Bearer 你的网关密码' \
  -H 'Content-Type: application/json' \
  -d '{"model": "openclaw:main", "messages": [{"role":"user","content":"你好"}]}'
​

支持流式输出：加 "stream": true，响应格式为 SSE，以 data: [DONE] 结束。

OpenResponses 兼容端点

{
  gateway: {
    http: { endpoints: { responses: { enabled: true } } },
  },
}
​

curl -sS http://127.0.0.1:18789/v1/responses \
  -H 'Authorization: Bearer 你的网关密码' \
  -H 'Content-Type: application/json' \
  -d '{"model": "openclaw:main", "input": "你好"}'
​

Tools Invoke 端点（默认开启）

curl -sS http://127.0.0.1:18789/tools/invoke \
  -H 'Authorization: Bearer 你的网关密码' \
  -H 'Content-Type: application/json' \
  -d '{"tool": "sessions_list", "action": "json", "args": {}}'
​

Agent 选择

通过 model 字段选择 Agent："openclaw:main"、"openclaw:beta"、"agent:ops"。
或通过 Header：x-openclaw-agent-id: main。

CLI Backends（本地 AI CLI 备用通道）

openclaw agent --message "hi" --model claude-cli/opus-4.6
openclaw agent --message "hi" --model codex-cli/gpt-5.4
​

作为 fallback 配置：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["claude-cli/opus-4.6"],
      },
    },
  },
}
​

限制：CLI Backend 模式无 OpenClaw 工具调用，不支持流式输出。

Gateway 通过 exec 工具运行 Shell 命令，process 工具管理后台任务。

exec 工具参数

前台命令直接返回输出；后台命令返回 sessionId，后续用 process 工具查询。

process 工具操作

{
  tools: {
    exec: {
      backgroundMs: 10000,   // 自动后台化延迟（毫秒）
      timeoutSec: 1800,      // 超时（秒）
      cleanupMs: 1800000,    // 完成后清理延迟（毫秒）
      notifyOnExit: true,    // 后台任务退出时触发心跳通知
    },
  },
}
​

后台任务在进程重启时丢失（不持久化到磁盘）。

升级后大多数问题是配置漂移或更严格的默认值被强制执行：

1. 认证和 URL 行为变化

   • gateway.mode=remote 时 CLI 可能指向远程
   • 检查 openclaw config get gateway.mode 和 gateway.auth.mode

2. 绑定和认证规则更严格

   • 非 loopback 绑定现在必须配置认证
   • gateway.token（旧）不等于 gateway.auth.token（新）

3. 配对和设备身份状态变化

   • 检查 openclaw devices list 和 openclaw pairing list

如果服务配置和运行时不一致，重新安装服务元数据：

openclaw gateway install --force
openclaw gateway restart
​

openclaw browser status
openclaw browser start --browser-profile openclaw
openclaw browser profiles
openclaw doctor
​

常见问题：

• Failed to start Chrome CDP on port — 浏览器进程启动失败
• browser.executablePath not found — 配置的路径无效
• Chrome extension relay is running, but no tab is connected — 扩展 relay 未连接