OpenClaw 设计与实现

附录 A：OpenClaw 配置速查表

作者 杨艺韬 · 3,785 字 · 发布于 · 更新于

本附录列出 OpenClaw 最常用的配置项。所有取值均对照 openclaw/openclaw v2026.3.31（commit 213a704）的 src/config/types*.ts、src/config/defaults.ts 与仓库自带的 docs/gateway/configuration-reference.md 核实。

如何使用本附录

配置文件是 ~/.openclaw/openclaw.json——扩展名是 .json，但按 JSON5 解析，因此允许注释、尾逗号和无引号键名（源码里 CONFIG_FILENAME = "openclaw.json"，见 src/config/paths.ts）。三种覆盖方式：

  1. 配置文件：在 openclaw.json 中以嵌套对象书写，如 { gateway: { port: 19001 } }
  2. 环境变量：OPENCLAW_CONFIG_PATH 换配置路径、OPENCLAW_STATE_DIR 换状态目录，另有若干凭证变量（见 §A.9）；配置里的任意字符串还支持 ${VAR_NAME} 替换
  3. CLI 参数：如 openclaw gateway --port 19001，以及根级 --profile <name> / --dev 整体切换实例

查阅建议：表中"默认值"列为 — 表示该项没有默认值，需要显式设置才生效。标记为 SecretInput 的字段既接受明文字符串，也接受 SecretRef 对象 { source: "env" | "file" | "exec", provider: "<提供者别名，如 default>", id: "..." }。完整 Schema 可用 openclaw config schema 导出，逐字段说明见仓库内的 docs/gateway/configuration-reference.md。

A.1 Gateway 配置（gateway.*）

配置项 类型 默认值 说明
gateway.port number 18789 Gateway WS + HTTP 复用端口。优先级：--port > OPENCLAW_GATEWAY_PORT > 本项 > 18789
gateway.bind string "loopback" 绑定模式：auto / lan / loopback / tailnet / custom（写模式名，不要写 0.0.0.0 这类主机别名）
gateway.customBindHost string — bind="custom" 时的自定义 IP
gateway.mode string —（openclaw setup / 引导向导写入 "local"） "local" 本地启动 / "remote" 仅连接远程。openclaw gateway 只在值为 "local" 时启动——未设置或为 remote 都会拒绝（除非加 --allow-unconfigured），见 src/cli/gateway-cli/run.ts
gateway.trustedProxies string[] — 可信反代 IP，命中后才信任 x-forwarded-for
gateway.allowRealIpFallback boolean false 缺 x-forwarded-for 时是否接受 x-real-ip（默认 fail-closed）
gateway.tools.deny string[] — 在 HTTP POST /tools/invoke 默认拒绝清单之外再加禁用工具
gateway.tools.allow string[] — 从默认拒绝清单中移除某些工具
gateway.channelHealthCheckMinutes number 5 通道健康检查间隔（分钟），0 禁用
gateway.channelStaleEventThresholdMinutes number 30 通道无事件超时阈值（分钟），应 ≥ 上一项
gateway.channelMaxRestartsPerHour number 10 每通道/账号每小时最大自动重启次数

A.1.1 认证（gateway.auth.*）

配置项 类型 默认值 说明
gateway.auth.mode string "token"（未设 mode 且只配了 password 时取 password） 认证模式：none / token / password / trusted-proxy
gateway.auth.token SecretInput — token 模式的共享密钥；token 模式下缺失时网关启动会自动生成一个（src/gateway/startup-auth.ts）
gateway.auth.password SecretInput — password 模式的共享口令
gateway.auth.allowTailscale boolean tailscale.mode="serve" 且 auth.mode 不是 password / trusted-proxy 时为 true 允许 Tailscale Serve 身份 Header 通过 Control UI / WS 认证
gateway.auth.trustedProxy object — mode="trusted-proxy" 时必填（如 userHeader）
gateway.auth.rateLimit.maxAttempts number 10 每 IP 失败次数上限
gateway.auth.rateLimit.windowMs number 60000 滑动窗口（毫秒）
gateway.auth.rateLimit.lockoutMs number 300000 锁定时长（毫秒）
gateway.auth.rateLimit.exemptLoopback boolean true 回环地址是否豁免限速

同时配置了 token 与 password 时必须显式指定 mode，否则启动与服务安装/修复流程会失败。非回环绑定必须配认证。

A.1.2 TLS（gateway.tls.*）

配置项 类型 默认值 说明
gateway.tls.enabled boolean false 启用 TLS
gateway.tls.autoGenerate boolean true 证书/私钥缺失时自动生成自签名证书
gateway.tls.certPath string — PEM 证书路径
gateway.tls.keyPath string — PEM 私钥路径
gateway.tls.caPath string — 可选 PEM CA 包（mTLS 或自定义根）

A.1.3 热重载（gateway.reload.*）

配置项 类型 默认值 说明
gateway.reload.mode string "hybrid" 重载策略：off / restart / hot / hybrid
gateway.reload.debounceMs number 300 防抖窗口（毫秒）
gateway.reload.deferralTimeoutMs number 300000 发出 SIGUSR1 前等待在途操作完成的上限（5 分钟）

A.1.4 远程连接（gateway.remote.*）

配置项 类型 默认值 说明
gateway.remote.enabled boolean true（类型注释所写） 是否启用远程网关相关能力；v2026.3.31 的 src/、apps/、extensions/ 中未见读取该字段的实现
gateway.remote.url string — 远程 Gateway WebSocket URL（ws:// / wss://）
gateway.remote.transport string "ssh" macOS App 的远程传输方式：ssh（默认，隧道） / direct
gateway.remote.token SecretInput — 远程认证 Token（这是客户端凭证，不配置本机网关认证）
gateway.remote.password SecretInput — 远程认证口令
gateway.remote.tlsFingerprint string — 期望的 TLS 证书指纹（sha256）
gateway.remote.sshTarget / .sshIdentity string — SSH 隧道目标与身份文件

A.1.5 Tailscale 与 Control UI

配置项 类型 默认值 说明
gateway.tailscale.mode string "off" off / serve（仅 tailnet） / funnel（公网，必须配认证）
gateway.controlUi.enabled boolean true 启用 Control UI
gateway.controlUi.basePath string ""（挂在根路径） Control UI 挂载路径前缀。src/gateway/control-ui-shared.ts:9 的 normalizeControlUiBasePath() 在未配置时返回空串——类型注释里的 "/openclaw" 只是示例，不是默认值
gateway.controlUi.allowedOrigins string[] — 浏览器来源白名单；非回环来源必须显式配置

A.2 会话配置（session.*）

配置项 类型 默认值 说明
session.scope string "per-sender" 群聊场景的会话分组：per-sender / global
session.dmScope string "main" 私聊分组：main / per-peer / per-channel-peer / per-account-channel-peer
session.identityLinks Record — 把同一个人在不同通道的身份归并为一个会话
session.resetTriggers string[] ["/new", "/reset"] 触发重置的命令关键词
session.store string ~/.openclaw/agents/{agentId}/sessions/sessions.json 会话存储路径
session.parentForkMaxTokens number 100000 父会话超过此 token 数则不再继承其历史，0 关闭该保护
session.typingMode string 继承 agents.defaults.typingMode 会话级打字指示覆盖：never / instant / thinking / message
session.agentToAgent.maxPingPongTurns number 5 Agent 间往返回合上限（0–5，0 禁用）
session.sendPolicy object default: "allow" 发送策略规则表；任一规则命中 deny 即拒绝（deny 优先）

A.2.1 会话重置（session.reset.* / session.resetByType.*）

配置项 类型 默认值 说明
session.reset.mode string "daily" 重置模式：daily / idle
session.reset.atHour number 4 daily 模式下的本地重置小时（0–23）
session.reset.idleMinutes number — idle 模式的空闲滑动窗口（分钟）
session.resetByType.<type> object — 按 direct / group / thread 分别覆盖上面的策略

两种模式同时配置时，先到期的那个生效。

A.2.2 会话存储维护（session.maintenance.*）

配置项 类型 默认值 说明
session.maintenance.mode string "warn" warn 只告警；enforce 实际清理
session.maintenance.pruneAfter duration "30d" 陈旧条目的年龄阈值
session.maintenance.maxEntries number 500 sessions.json 最大条目数
session.maintenance.rotateBytes size "10mb" 超过则轮转 sessions.json
session.maintenance.resetArchiveRetention duration | false 同 pruneAfter 重置归档的保留期
session.maintenance.maxDiskBytes size — 会话目录磁盘预算（可选硬上限）
session.maintenance.highWaterBytes size maxDiskBytes 的 80% 清理后的目标水位

A.3 Agent 配置（agents.defaults.* / agents.list[]）

全局默认写在 agents.defaults，单个 Agent 的覆盖写在 agents.list[]（按 id 匹配）。

配置项 类型 默认值 说明
agents.defaults.workspace string ~/.openclaw/workspace Agent 工作区目录
agents.defaults.model string | object — "provider/model" 字符串，或 { primary, fallbacks } 对象
agents.defaults.models Record — 模型目录与 /model 白名单，每项可带 alias 与 params
agents.defaults.imageModel / imageGenerationModel / pdfModel string | object — 视觉、图像生成、PDF 三条独立的模型路由
agents.defaults.contextTokens number 随模型 上下文窗口上限；小于模型自身窗口时作为封顶生效
agents.defaults.maxConcurrent number 4 跨会话的最大并行 Agent 运行数（单会话内仍串行）
agents.defaults.timeoutSeconds number — 单次运行超时
agents.defaults.thinkingDefault string 随模型（Claude 4.6 为 adaptive，其他推理模型 low，否则 off） 默认思考档位（off/minimal/low/medium/high/xhigh/adaptive）
agents.defaults.verboseDefault string "off" off / on / full
agents.defaults.elevatedDefault string "on" off / on / ask / full
agents.defaults.typingMode string 直聊/被提及 instant，群聊未提及 message never / instant / thinking / message
agents.defaults.typingIntervalSeconds number — 打字指示刷新间隔
agents.defaults.sandbox object — 沙箱配置，见 §A.6.4
agents.list[].id string — Agent 标识
agents.list[].tools / .params / .workspace object / object / string — 单 Agent 覆盖。注意 tools.profile 以 Agent 级为准（agents.list[].tools.profile ?? tools.profile），可以比全局更宽；allow / deny 则在全局策略之后逐级收窄

内建模型别名

以下别名只在对应模型已出现在 agents.defaults.models 中时才生效；你自己配置的别名优先级更高。

别名 解析为
opus anthropic/claude-opus-4-6
sonnet anthropic/claude-sonnet-4-6
gpt openai/gpt-5.4
gpt-mini openai/gpt-5-mini
gemini google/gemini-3.1-pro-preview
gemini-flash google/gemini-3-flash-preview
gemini-flash-lite google/gemini-3.1-flash-lite-preview

系统级默认模型是 anthropic/claude-opus-4-6（DEFAULT_PROVIDER + DEFAULT_MODEL，见 src/agents/defaults.ts）。

A.4 模型与 Provider（models.*）

models.providers.<providerId> 定义自定义 Provider 与其模型列表。

配置项 类型 默认值 说明
models.providers.<id>.baseUrl string — Provider API 基址
models.providers.<id>.apiKey SecretInput — Provider 密钥
models.providers.<id>.models[].id string — 模型 ID
models.providers.<id>.models[].name string — 显示名称
models.providers.<id>.models[].contextWindow number 200000（DEFAULT_CONTEXT_TOKENS） 上下文窗口（会被上下文守卫读取）
models.providers.<id>.models[].maxTokens number 8192 与 contextWindow 取小 单次最大输出 Token（DEFAULT_MODEL_MAX_TOKENS）
models.providers.<id>.models[].cost.input / .output / .cacheRead / .cacheWrite number 0 单价，用于 openclaw gateway usage-cost 汇总

A.5 通道配置（channels.*）

各通道的密钥字段名并不统一，这是最容易配错的地方——请以本表为准。

配置项 类型 说明
channels.telegram.botToken SecretInput Telegram Bot Token
channels.discord.token SecretInput Discord Bot Token（注意是 token，不是 botToken）
channels.slack.botToken SecretInput Slack Bot Token（xoxb-）
channels.slack.appToken SecretInput Slack App Token（xapp-，Socket Mode）
channels.whatsapp.* object 走 Baileys Web，有已链接会话即自动启动，无 token 字段
channels.<provider>.enabled boolean 是否启用该通道
channels.<provider>.dmPolicy string pairing（默认） / allowlist / open / disabled
channels.<provider>.allowFrom string[] 私聊来源白名单
channels.<provider>.groups Record 群聊策略（"*" 为通配，可设 requireMention、systemPrompt、skills 等）。Discord 对应键为 guilds，Slack 为 channels
channels.<provider>.healthMonitor.enabled boolean 单通道关闭健康监控重启
channels.<provider>.accounts.<accountId> object 多账号配置，优先级高于通道级

A.6 工具与安全配置

A.6.1 工具（tools.*）

配置项 类型 默认值 说明
tools.profile string 本地引导默认写入 "coding" minimal / coding / messaging / full
tools.allow string[] — 允许的工具（支持 group:* 与 * 通配）；只能在 profile 结果上再收窄
tools.alsoAllow string[] — 在 profile 的允许列表上追加工具
tools.deny string[] — 禁止的工具，deny 优先于 allow
tools.byProvider.<provider或model> object — 针对特定 Provider/模型进一步收紧
tools.elevated.enabled boolean true（未设即启用） 提权（宿主机）exec 总开关；发送者还须列在下一项 allowFrom 中，未列出即无人可提权
tools.elevated.allowFrom Record — 按通道列出可提权的发送者
tools.loopDetection.enabled boolean false 工具循环检测，默认关闭

工具分组（用于 allow/deny）：group:runtime（exec、process、code_execution）、group:fs（read/write/edit/apply_patch）、group:sessions、group:memory、group:web、group:ui、group:automation、group:messaging、group:nodes、group:agents、group:media、group:openclaw（除 read/write/edit/apply_patch/exec/process 外的核心工具）、group:plugins（插件工具），定义见 src/agents/tool-catalog.ts。

A.6.2 Exec 工具（tools.exec.*）

配置项 类型 默认值 说明
tools.exec.host string "auto" auto / sandbox / gateway / node
tools.exec.security string 按 host 分流 deny / allowlist / full。未显式配置时由 exec 落地的主机决定：sandbox 取 deny，gateway/node 取 allowlist（src/agents/bash-tools.exec.ts；src/config/types.tools.ts 的注释写 default: deny，与实现不符）
tools.exec.ask string "on-miss" off / on-miss / always
tools.exec.safeBins string[] cut/uniq/head/tail/tr/wc 免 allowlist 的"仅读 stdin"流过滤器；每项须有内置或 safeBinProfiles 自定义的参数 profile，否则被忽略并告警。普通命令放行请用审批白名单
tools.exec.strictInlineEval boolean — 对 python -c / node -e 这类内联求值强制重新审批
tools.exec.pathPrepend string[] — 执行时前置到 PATH 的目录
tools.exec.timeoutSec number 1800 单条命令超时（秒）
tools.exec.backgroundMs number 10000 超过该时长（毫秒）转入后台

A.6.3 来源白名单

来源白名单是按通道配置的，写在 channels.<provider>.allowFrom / .groups 下，没有全局的 allowFrom.users / allowFrom.groups 顶层键。

A.6.4 Sandbox（agents.defaults.sandbox.*）

配置项 类型 默认值 说明
.mode string "off" 何时启用沙箱：off / non-main / all
.backend string "docker" 沙箱后端：docker / ssh / openshell（插件提供）
.scope string "agent" 容器复用粒度：session / agent / shared
.workspaceAccess string "none" 工作区挂载权限：none / ro / rw
.docker.image string openclaw-sandbox:bookworm-slim 镜像
.docker.network string none 容器网络
.docker.readOnlyRoot boolean true 只读根文件系统
.docker.capDrop string[] ["ALL"] 丢弃的 Linux 能力
.docker.memory / .cpus / .pidsLimit string / number / number —（不设即不限，示例 1g / 1 / 256） 资源限制

A.7 定时任务（cron.*）

注意：具体的定时作业不写在配置文件里，而是由 openclaw cron 命令管理、存在独立的 cron store 中。配置文件里的 cron.* 只是调度器的全局参数。

配置项 类型 默认值 说明
cron.enabled boolean true（未设即启用） 启用调度器，设 false 关闭
cron.maxConcurrentRuns number 1 最大并发作业数
cron.sessionRetention duration | false "24h" 已完成的隔离作业会话保留时长
cron.runLog.maxBytes number | string 2000000 单个作业运行日志上限
cron.runLog.keepLines number 2000 触发裁剪时保留的最新行数
cron.retry.maxAttempts number 3 一次性作业的瞬时错误重试次数（0–10）
cron.retry.backoffMs number[] [30000, 60000, 300000] 各次重试的退避毫秒数
cron.retry.retryOn string[] 全部瞬时类型 rate_limit / overloaded / network / timeout / server_error
cron.webhookToken SecretInput — webhook 投递的 bearer token

A.8 语音：TTS（messages.tts.*）与 Talk（talk.*）

配置项 类型 默认值 说明
messages.tts.auto string "off" off / always / inbound / tagged
messages.tts.mode string "final" final 只念最终回复 / all
messages.tts.provider string — 如 elevenlabs、openai
messages.tts.summaryModel string 继承主模型 自动摘要用的模型
messages.tts.maxTextLength number 4096 送入 TTS 的文本硬上限（字符）
messages.tts.timeoutMs number 30000 TTS 请求超时（毫秒）
messages.tts.providers.<provider>.apiKey SecretInput — provider 密钥（旧写法 messages.tts.<provider>.apiKey 仍兼容）；缺省回落到 ELEVENLABS_API_KEY / XI_API_KEY / OPENAI_API_KEY
talk.provider / talk.providers.<id>.* string / object — 当前 Talk 语音 provider 及其配置（voiceId、voiceAliases、modelId、apiKey 等）
talk.voiceId string — Talk 模式默认语音 ID（顶层写法为兼容旧版保留；macOS App 回落 ELEVENLABS_VOICE_ID / SAG_VOICE_ID）
talk.voiceAliases Record — 语音友好名映射（同为兼容字段）
talk.interruptOnSpeech boolean true 用户说话时打断播放
talk.silenceTimeoutMs number 平台默认（macOS/Android 700ms，iOS 900ms） 静默多久后提交转写

A.9 环境变量

环境变量 说明
OPENCLAW_CONFIG_PATH 自定义配置文件路径
OPENCLAW_STATE_DIR 自定义状态目录（配置、会话、凭证都在其下）
OPENCLAW_GATEWAY_PORT 网关端口（优先级高于 gateway.port）
OPENCLAW_GATEWAY_TOKEN Gateway 认证 Token
OPENCLAW_GATEWAY_PASSWORD Gateway 认证口令
OPENCLAW_LOG_LEVEL 日志级别覆盖（文件与控制台）
OPENCLAW_HIDE_BANNER 隐藏 CLI Banner
OPENCLAW_PROFILE 当前 profile（等价于根级 --profile）
ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY 等 各 Provider 密钥
ELEVENLABS_API_KEY / XI_API_KEY TTS 密钥回落

另外两条机制值得知道：配置里的 env 段可以内联注入环境变量（仅当进程环境中不存在该键时生效）；.env 文件从当前目录和 ~/.openclaw/.env（或 $OPENCLAW_STATE_DIR/.env）加载，同样不覆盖已存在的变量。注意当前目录的 .env 被视为不可信：ANTHROPIC_API_KEY、OPENAI_API_KEY、OPENCLAW_GATEWAY_TOKEN、OPENCLAW_STATE_DIR、代理变量及 *_BASE_URL 等键会被忽略（src/infra/dotenv.ts），这些应写进 ~/.openclaw/.env 或进程环境。

A.10 默认端口

端口不是各自独立写死的，而是从网关端口派生出来的（src/config/port-defaults.ts）——改了 gateway.port，其余端口跟着平移。

端口 派生方式 用途
18789 基准 Gateway 主端口（WS + HTTP 复用）
18790 网关端口 + 1 Bridge 端口
18791 网关端口 + 2 Browser Control 端口
18793 网关端口 + 4 Canvas Host 端口
18800-18899 Browser Control 端口 + 9 起，宽度 100 Browser CDP 端口范围

这也解释了 --dev（网关端口 19001）为什么能和正式实例共存：整组端口一起挪了位置。

提示：完整配置 Schema 可通过 openclaw config schema 命令查看；仓库内 docs/gateway/configuration-reference.md 有逐字段的权威说明，类型定义在 src/config/types*.ts。