搞技术的都知道英文文档读起来没什么问题但有些配置项的命名确实不太好理解再加上不同版本的文档可能有变动找一个准确的中文参考有时候能省下大量时间。我最近花了几天时间把OpenClaw的配置参数系统过了一遍把自己翻译整理的内容分享出来希望能帮到需要的朋友。声明一下这不是官方翻译是我根据实际使用经验和源码注释做的理解和整理如果有不准确的地方欢迎指正。OpenClaw最新版本一键部署包下载地址TopClaw官网一键免费部署OpenClaw一、核心配置区块OpenClaw的配置文件通常采用YAML或者JSON格式按照功能模块分成不同的区块。我先从最核心的几个开始说。gateway这是网关相关的配置。gateway.host设置服务监听的主机地址默认是127.0.0.1意味着只接受本机连接。如果你想从局域网其他设备访问需要改成0.0.0.0。gateway.port是端口号默认8080。gateway.tls.enabled控制是否启用HTTPS如果开启的话还需要配置证书路径和密钥路径。对于本地开发来说一般不需要开TLS但如果是远程部署建议打开。agentAgent是OpenClaw里最重要的概念它代表一个具体的AI助手实例。agent.name是Agent的显示名称agent.model指定使用的AI模型。agent.system_prompt是系统提示词用于设定Agent的行为和角色。这个字段支持多行文本你也可以把它指向一个外部文件用file://前缀加路径的方式引用。agent.max_tokens控制单次请求允许的最大token数这个值不应该超过模型本身的上限。agent.temperature控制输出的随机性值域0到20表示完全确定性输出2表示高度随机。日常使用0.7到0.9是一个比较合理的范围。agent.top_p是核采样的概率阈值和temperature配合使用通常设成0.9左右。二、工具与技能配置skills这是技能模块的配置。skills.enabled控制是否启用技能系统默认为true。skills.directory指定技能文件的存放目录支持绝对路径和相对路径相对于工作目录。skills.auto_load控制是否在启动时自动加载所有已安装的技能。如果你有很多技能但不是每次都需要全部加载可以关掉这个选项然后在需要的时候手动启用特定的技能。tools工具配置区。tools.browser.enabled控制浏览器自动化功能是否开启开启后可以使用网页操作相关的指令。tools.browser.headless设置是否使用无头模式运行浏览器服务器部署时一般设为true本地开发可以设为false方便调试。tools.file.allowed_paths设定文件操作允许访问的路径范围这是一个安全相关的配置建议只开放必要的目录。三、消息与通信配置messaging消息模块配置。messaging.channels是一个列表每个元素定义一个消息通道。常用的通道类型包括webchat网页聊天、telegramTelegram机器人、discordDiscord机器人等。每个通道需要配置type、enabled以及通道特有的参数。比如Telegram通道需要配置bot_tokenDiscord通道需要配置token和guild_id。messaging.rate_limit设置消息发送的频率限制单位是每分钟消息数。默认值一般够用但如果你的Agent会在短时间内发送大量消息比如处理批量任务可能需要适当调高。注意各平台有自己的API频率限制设置值不应该超过平台允许的上限。messaging.retry_policy重试策略。retry_policy.max_retries是最大重试次数retry_policy.backoff_factor是退避因子单位秒retry_policy.backoff_type是退避类型支持fixed固定间隔和exponential指数退避。推荐用指数退避在网络不稳定的情况下表现更好。四、存储与缓存配置storage存储相关配置。storage.type指定存储后端类型支持local本地文件和database数据库等。storage.path设置本地存储的根目录。storage.max_file_size设定单个文件的最大允许大小默认是10MB。如果你经常需要处理大文件记得调高这个值。cache缓存配置。cache.enabled控制是否启用缓存。cache.type支持memory内存缓存和disk磁盘缓存。cache.ttl设置缓存的有效期秒。cache.max_size限制缓存的最大容量。对于频繁访问但不常变更的数据比如模型配置、用户偏好设置等开启缓存可以明显提升响应速度。五、日志与监控配置logging日志模块配置。logging.level设置日志级别从低到高依次是debug、info、warn、error、fatal。logging.format控制日志输出格式支持text纯文本和json结构化JSON。后者适合接入日志收集系统。logging.output指定日志输出的目标支持stdout标准输出、file文件和both两者同时。logging.file.path设置日志文件的路径。logging.file.rotation控制日志轮转策略支持按大小size和按时间time两种模式。logging.file.max_size是单个日志文件的最大大小字节。logging.file.max_files是保留的历史日志文件数量。monitoring监控配置。monitoring.enabled控制是否启用监控端点。monitoring.port设置监控服务的端口如果和主服务不同。monitoring.metrics_path设置指标数据的访问路径默认是/metrics输出的是Prometheus格式的指标数据。六、安全配置security安全相关配置。security.auth.enabled控制是否启用身份验证。security.auth.method指定认证方式支持token和oauth2等。security.cors.allowed_origins设置允许跨域访问的来源列表生产环境不建议用通配符应该明确指定允许的域名。security.rate_limit设置API级别的请求频率限制。security.timeout设置请求处理的超时时间。security.sanitize_input控制是否对输入内容进行清洗过滤开启后可以防止一些常见的注入攻击。建议在对外暴露服务的场景下开启这个选项。七、性能调优参数performance性能调优区块。performance.concurrency设置并发处理的最大数量。performance.queue_size设置任务队列的缓冲区大小。performance.worker_threads指定工作线程数默认会根据CPU核心数自动判断。performance.batch_size设置批量处理的单批大小适用于需要同时处理多条消息的场景。performance.memory_limit设置内存使用上限超过限制时会触发缓存清理和资源回收。performance.gc_interval设置垃圾回收的间隔时间。这些参数在资源受限的环境中比如低配服务器或容器比较有用可以根据实际情况微调。写在最后以上是OpenClaw主要配置参数的中文说明。实际使用中你不需要把每个参数都配一遍——大部分参数有合理的默认值你只需要关注和你的使用场景直接相关的那些。建议的步骤是先用默认配置跑起来然后根据实际需求和遇到的问题有针对性地调整特定参数。配置这个东西够用就行过度优化反而容易引入新问题。如果你发现有哪些参数我漏掉了或者解释得不够清楚欢迎在评论区补充讨论。
OpenClaw中文文档，全网最全配置参数翻译说明
搞技术的都知道英文文档读起来没什么问题但有些配置项的命名确实不太好理解再加上不同版本的文档可能有变动找一个准确的中文参考有时候能省下大量时间。我最近花了几天时间把OpenClaw的配置参数系统过了一遍把自己翻译整理的内容分享出来希望能帮到需要的朋友。声明一下这不是官方翻译是我根据实际使用经验和源码注释做的理解和整理如果有不准确的地方欢迎指正。OpenClaw最新版本一键部署包下载地址TopClaw官网一键免费部署OpenClaw一、核心配置区块OpenClaw的配置文件通常采用YAML或者JSON格式按照功能模块分成不同的区块。我先从最核心的几个开始说。gateway这是网关相关的配置。gateway.host设置服务监听的主机地址默认是127.0.0.1意味着只接受本机连接。如果你想从局域网其他设备访问需要改成0.0.0.0。gateway.port是端口号默认8080。gateway.tls.enabled控制是否启用HTTPS如果开启的话还需要配置证书路径和密钥路径。对于本地开发来说一般不需要开TLS但如果是远程部署建议打开。agentAgent是OpenClaw里最重要的概念它代表一个具体的AI助手实例。agent.name是Agent的显示名称agent.model指定使用的AI模型。agent.system_prompt是系统提示词用于设定Agent的行为和角色。这个字段支持多行文本你也可以把它指向一个外部文件用file://前缀加路径的方式引用。agent.max_tokens控制单次请求允许的最大token数这个值不应该超过模型本身的上限。agent.temperature控制输出的随机性值域0到20表示完全确定性输出2表示高度随机。日常使用0.7到0.9是一个比较合理的范围。agent.top_p是核采样的概率阈值和temperature配合使用通常设成0.9左右。二、工具与技能配置skills这是技能模块的配置。skills.enabled控制是否启用技能系统默认为true。skills.directory指定技能文件的存放目录支持绝对路径和相对路径相对于工作目录。skills.auto_load控制是否在启动时自动加载所有已安装的技能。如果你有很多技能但不是每次都需要全部加载可以关掉这个选项然后在需要的时候手动启用特定的技能。tools工具配置区。tools.browser.enabled控制浏览器自动化功能是否开启开启后可以使用网页操作相关的指令。tools.browser.headless设置是否使用无头模式运行浏览器服务器部署时一般设为true本地开发可以设为false方便调试。tools.file.allowed_paths设定文件操作允许访问的路径范围这是一个安全相关的配置建议只开放必要的目录。三、消息与通信配置messaging消息模块配置。messaging.channels是一个列表每个元素定义一个消息通道。常用的通道类型包括webchat网页聊天、telegramTelegram机器人、discordDiscord机器人等。每个通道需要配置type、enabled以及通道特有的参数。比如Telegram通道需要配置bot_tokenDiscord通道需要配置token和guild_id。messaging.rate_limit设置消息发送的频率限制单位是每分钟消息数。默认值一般够用但如果你的Agent会在短时间内发送大量消息比如处理批量任务可能需要适当调高。注意各平台有自己的API频率限制设置值不应该超过平台允许的上限。messaging.retry_policy重试策略。retry_policy.max_retries是最大重试次数retry_policy.backoff_factor是退避因子单位秒retry_policy.backoff_type是退避类型支持fixed固定间隔和exponential指数退避。推荐用指数退避在网络不稳定的情况下表现更好。四、存储与缓存配置storage存储相关配置。storage.type指定存储后端类型支持local本地文件和database数据库等。storage.path设置本地存储的根目录。storage.max_file_size设定单个文件的最大允许大小默认是10MB。如果你经常需要处理大文件记得调高这个值。cache缓存配置。cache.enabled控制是否启用缓存。cache.type支持memory内存缓存和disk磁盘缓存。cache.ttl设置缓存的有效期秒。cache.max_size限制缓存的最大容量。对于频繁访问但不常变更的数据比如模型配置、用户偏好设置等开启缓存可以明显提升响应速度。五、日志与监控配置logging日志模块配置。logging.level设置日志级别从低到高依次是debug、info、warn、error、fatal。logging.format控制日志输出格式支持text纯文本和json结构化JSON。后者适合接入日志收集系统。logging.output指定日志输出的目标支持stdout标准输出、file文件和both两者同时。logging.file.path设置日志文件的路径。logging.file.rotation控制日志轮转策略支持按大小size和按时间time两种模式。logging.file.max_size是单个日志文件的最大大小字节。logging.file.max_files是保留的历史日志文件数量。monitoring监控配置。monitoring.enabled控制是否启用监控端点。monitoring.port设置监控服务的端口如果和主服务不同。monitoring.metrics_path设置指标数据的访问路径默认是/metrics输出的是Prometheus格式的指标数据。六、安全配置security安全相关配置。security.auth.enabled控制是否启用身份验证。security.auth.method指定认证方式支持token和oauth2等。security.cors.allowed_origins设置允许跨域访问的来源列表生产环境不建议用通配符应该明确指定允许的域名。security.rate_limit设置API级别的请求频率限制。security.timeout设置请求处理的超时时间。security.sanitize_input控制是否对输入内容进行清洗过滤开启后可以防止一些常见的注入攻击。建议在对外暴露服务的场景下开启这个选项。七、性能调优参数performance性能调优区块。performance.concurrency设置并发处理的最大数量。performance.queue_size设置任务队列的缓冲区大小。performance.worker_threads指定工作线程数默认会根据CPU核心数自动判断。performance.batch_size设置批量处理的单批大小适用于需要同时处理多条消息的场景。performance.memory_limit设置内存使用上限超过限制时会触发缓存清理和资源回收。performance.gc_interval设置垃圾回收的间隔时间。这些参数在资源受限的环境中比如低配服务器或容器比较有用可以根据实际情况微调。写在最后以上是OpenClaw主要配置参数的中文说明。实际使用中你不需要把每个参数都配一遍——大部分参数有合理的默认值你只需要关注和你的使用场景直接相关的那些。建议的步骤是先用默认配置跑起来然后根据实际需求和遇到的问题有针对性地调整特定参数。配置这个东西够用就行过度优化反而容易引入新问题。如果你发现有哪些参数我漏掉了或者解释得不够清楚欢迎在评论区补充讨论。
