Gateway 配置参考

~/.openclaw/openclaw.json 的核心配置参考。格式为 JSON5（支持注释和尾随逗号），所有字段均可选，缺省时使用安全默认值。

查看实时 schema：openclaw config schema

Models

{
  models: {
    mode: "merge",  // merge | replace
    pricing: { enabled: false },
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",
      },
    },
  },
}

models.mode：merge（默认）或 replace
models.pricing.enabled：控制后台定价目录抓取，false 时跳过 OpenRouter/LiteLLM 定价获取

MCP

{
  mcp: {
    sessionIdleTtlMs: 600000,  // 默认 10 分钟，0 禁用空闲驱逐
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http",  // streamable-http | sse
        headers: { Authorization: "Bearer ${MCP_REMOTE_TOKEN}" },
      },
    },
  },
}

mcp.* 变更热应用，移除的 mcp.servers 条目立即回收。

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",  // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    entries: {
      "image-lab": { apiKey: "GEMINI_KEY_HERE" },
      peekaboo: { enabled: true },
    },
  },
}

Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    deny: [],
    load: { paths: ["~/Projects/oss/voice-call-plugin"] },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: { allowPromptInjection: false },
        config: { provider: "twilio" },
      },
    },
  },
}

配置变更需要重启 Gateway
allow：可选白名单（只加载列出的插件），deny 优先
bundledDiscovery：新配置默认 "allowlist"，迁移旧配置写 "compat"
plugins.entries.<id>.hooks.allowPromptInjection：false 时阻止 before_prompt_build 钩子

Browser

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true,  // 仅受信任私网访问时开启
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
    },
    profiles: {
      openclaw: { cdpPort: 18800 },
      user: { driver: "existing-session", attachOnly: true },
    },
  },
}

ssrfPolicy.dangerouslyAllowPrivateNetwork：默认禁用，严格限制私网导航
tabCleanup：空闲超时或超出上限时回收标签页

Gateway

{
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",  // auto | loopback | lan | tailnet | custom
    auth: {
      mode: "token",  // none | token | password | trusted-proxy
      token: "your-token",
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
      },
    },
    tailscale: { mode: "off" },  // off | serve | funnel
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      allowedOrigins: ["https://control.example.com"],
    },
    reload: { mode: "hybrid", debounceMs: 500 },
    tls: {
      enabled: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
    },
    nodes: {
      pairing: { autoApproveCidrs: ["192.168.1.0/24"] },
    },
    push: {
      apns: { relay: { baseUrl: "https://relay.example.com" } },
    },
  },
}

关键字段说明：

bind：loopback（默认）、lan（0.0.0.0）、tailnet（仅 Tailscale IP）
Docker 环境下默认 loopback 绑定在容器内监听 127.0.0.1，需设 bind: "lan" 才能接收外部流量
非 loopback 绑定必须配置 Gateway 认证
gateway.auth.mode: "none" 仅用于受信任的本地 loopback 场景
gateway.handshakeTimeoutMs：预认证 WebSocket 握手超时，默认 15000 ms

端口优先级

--port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789

多实例隔离

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

Hooks（Webhook）

{
  hooks: {
    enabled: true,
    token: "shared-secret",  // 必须与 gateway.auth.token 不同
    path: "/hooks",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

安全要点：

hooks.token 必须与 gateway.auth.token 不同
hooks.path 不能为 /
认证仅通过 Header（Authorization: Bearer ... 或 x-openclaw-token），拒绝 query string token

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: { maxBytes: "2mb", keepLines: 2000 },
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
    },
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
    },
  },
}

ACP

{
  acp: {
    enabled: true,
    backend: "acpx",
    defaultAgent: "main",
    maxConcurrentSessions: 10,
    stream: {
      coalesceIdleMs: 50,
      deliveryMode: "live",  // live | final_only
    },
    runtime: { ttlMinutes: 30 },
  },
}

Secrets

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

SecretRef 格式：{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Logging

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleStyle: "pretty",  // pretty | compact | json
    redactSensitive: "tools",  // off | tools
  },
}

Diagnostics（OpenTelemetry）

{
  diagnostics: {
    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      protocol: "http/protobuf",  // http/protobuf | grpc
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
    },
  },
}

Wiki AI

目录