OpenClaw配置文件openclaw.json参数详解与优化指南

2026-06-24阅读 0热度 0

json 运维

完成对OpenClaw配置文件的编辑后，必须重启网关服务以使变更生效。执行以下命令：

openclaw gateway restart

使用你熟悉的文本编辑器来修改配置文件，例如：

nano ~/.openclaw/openclaw.json

1. meta 配置段

"meta": {
  "lastTouchedVersion": "2026.3.13",
  "lastTouchedAt": "2026-03-16T05:36:26.133Z"
}

此段包含系统自动维护的元数据，记录了配置文件最后被修改的时间戳和对应的OpenClaw版本。这两个字段由程序自动更新，无需手动干预。

2. wizard 配置段

"wizard": {
  "lastRunAt": "2026-03-16T05:10:35.535Z",
  "lastRunVersion": "2026.3.13",
  "lastRunCommand": "configure",
  "lastRunMode": "local"
}

此段记录配置向导最后一次执行的详细信息，包括时间、版本、命令和运行模式。与meta段类似，这些信息由系统自动填充，通常无需修改。

3. auth 认证配置段

"auth": {
  "profiles": {
    "minimax:cn": {
      "provider": "minimax",
      "mode": "api_key"
    },
    "ollama:local": {
      "provider": "ollama",
      "mode": "api_key"
    }
  }
}

在此定义不同AI模型提供商的认证凭据。示例配置了两个档案：一个用于云端服务商Minimax，需提供有效的API密钥；另一个用于本地部署的Ollama服务，其api_key字段仅为保持格式一致，本地运行时可为任意值。

4. models 模型服务配置（核心）

"models": {
  "mode": "merge",
  "providers": {
    "minimax": {
      "baseUrl": "https://api.minimaxi.com/anthropic",
      "api": "anthropic-messages",
      "authHeader": true,
      "models": [{
        "id": "MiniMax-M2.5",
        "name": "MiniMax M2.5",
        "reasoning": true,
        "input": ["text"],
        "cost": {
          "input": 0.3,
          "output": 1.2,
          "cacheRead": 0.03,
          "cacheWrite": 0.12
        },
        "contextWindow": 200000,
        "maxTokens": 8192
      }]
    },
    "ollama": {
      "baseUrl": "http://127.0.0.1:11434",
      "api": "ollama",
      "apiKey": "ollama-local",
      "authHeader": true
    }
  }
}

这是配置文件的核心部分，用于定义模型来源和参数。

mode：模型加载策略。“merge”会合并所有提供商列出的模型；“override”则仅使用此处手动定义的模型列表。
providers：配置每个模型提供商。Minimax部分需详细定义模型ID、计费成本、上下文窗口等参数。Ollama部分通常只需指向本地API地址（默认127.0.0.1:11434）。

5. agents 智能体默认配置（最常改）

"agents": {
  "defaults": {
    "model": {
      "primary": "ollama/qwen2.5:7b",
      "fallbacks": ["minimax/MiniMax-M2.5"]
    },
    "models": {
      "minimax/MiniMax-M2.5": {
        "alias": "Minimax"
      },
      "ollama/qwen2.5:7b": {
        "alias": "Ollama-Qwen"
      }
    },
    "workspace": "/home/ubuntu24/.openclaw/workspace"
  }
}

此段配置智能体的默认行为，是调整最频繁的部分。

primary：指定默认主模型。格式为提供商/模型标识，例如ollama/qwen2.5:7b。
fallbacks：定义备用模型队列。当主模型不可用时，系统将按顺序尝试此处列出的模型。
alias：为模型设置一个简短的别名，便于在日志和界面中识别。
workspace：智能体执行文件操作时的默认工作目录路径，可根据需要修改。

6. tools 工具集配置

"tools": {
  "profile": "coding"
}

此配置决定智能体可访问的工具集类型。“coding”侧重编程与开发工具，“basic”提供核心功能，“full”则启用所有可用工具。根据你的主要使用场景进行选择。

7. commands 命令权限配置

"commands": {
  "native": "auto",
  "nativeSkills": "auto",
  "restart": true
}

控制智能体执行系统命令的权限级别。

native 与 nativeSkills：建议保持“auto”，由系统根据上下文智能判断是否允许执行，以平衡功能与安全。
restart：设为true时，若网关服务意外终止，系统将自动尝试重启。

8. session 会话策略配置

"session": {
  "dmScope": "per-channel-peer"
}

定义会话上下文的隔离策略。“per-channel-peer”是推荐设置，确保在不同频道或私聊对话中保持独立的会话历史，避免交叉污染。“global”则会让所有对话共享同一上下文。

9. hooks 日志钩子配置

"hooks": {
  "internal": {
    "enabled": true,
    "entries": {
      "command-logger": {
        "enabled": true
      }
    }
  }
}

配置系统内部的事件钩子，主要用于日志记录。默认启用的command-logger会记录所有命令执行详情，便于问题诊断与审计。通常保持默认开启状态。

10. channels 飞书通道配置

"channels": {
  "feishu": {
    "enabled": true,
    "connectionMode": "websocket",
    "verificationToken": "xxxxxxxxxxx",
    "dmPolicy": "pairing",
    "accounts": {
      "main": {
        "appId": "xxxxxxxxxxxxx",
        "appSecret": "xxxxxxxxxxxx",
        "botName": "xxxxxxx"
      }
    }
  }
}

用于配置飞书机器人通道。

enabled：总开关，true为启用。
botName：机器人在飞书客户端中显示的名称，可自定义。
关键凭证：appId、appSecret和verificationToken必须严格使用从飞书开放平台获取的原始值，任何修改都会导致连接失败。

11. gateway 网关服务配置

"gateway": {
  "port": 18789,
  "mode": "local",
  "bind": "loopback",
  "auth": {
    "mode": "token",
    "token": "xxxx"
  },
  "tailscale": {
    "mode": "off",
    "resetOnExit": false
  },
  "nodes": {
    "denyCommands": ["camera.snap", "camera.clip", "screen.record", "contacts.add", "calendar.add", "reminders.add", "sms.send"]
  }
}

网关是OpenClaw的核心服务入口，其配置决定了访问方式与安全策略。

port：网关服务监听的网络端口。
mode：“local”仅允许本机访问；“network”允许局域网内其他设备访问。
auth.mode：认证模式。“token”要求提供访问令牌，安全性更高；“none”则无需认证。
nodes.denyCommands：默认禁止执行的敏感命令列表，涉及摄像头、屏幕录制、通讯录等隐私操作，以增强安全性。

12. plugins 插件配置

"plugins": {
  "entries": {
    "feishu": {
      "enabled": true
    }
  }
}

此段是各个插件的全局启用开关。例如，将feishu.enabled设置为false将完全禁用飞书插件及其所有相关功能。

✅ 修改配置后必须执行

请务必记住，所有对openclaw.json配置文件的修改，都需要执行以下命令重启网关服务后方可生效：

openclaw gateway restart