Files
share/public/openclaw-docker-maintenance.html
T

348 lines
22 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1,viewport-fit=cover">
<meta name="color-scheme" content="light dark">
<meta name="robots" content="noindex,nofollow">
<title>OpenClaw Docker 部署维护指南:2 个主配置 + 3 个辅助文件</title>
<style>
:root{--bg:#fff;--fg:#202124;--muted:#727780;--line:#e6e8eb;--code:#f5f6f8;--link:#315c9b;--warn:#8a5a00}
@media(prefers-color-scheme:dark){:root{--bg:#18191b;--fg:#e8eaed;--muted:#9aa0a6;--line:#303236;--code:#222428;--link:#8ab4f8;--warn:#f6c453}}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%;background:var(--bg)}
body{margin:0;background:var(--bg);color:var(--fg);font-family:-apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Hiragino Sans GB","Microsoft YaHei",sans-serif;line-height:1.85;letter-spacing:.01em}
main{max-width:780px;margin:0 auto;padding:42px 22px 72px}
header{margin-bottom:30px;padding-bottom:18px;border-bottom:1px solid var(--line)}
.meta{display:flex;gap:8px;flex-wrap:wrap;color:var(--muted);font-size:14px}
.dot{opacity:.65}
.page-title{font-size:32px;line-height:1.3;margin:0 0 20px}
article{font-size:17px;word-break:break-word}
article h1{font-size:32px;line-height:1.3;margin:0 0 22px}article h2{font-size:23px;line-height:1.4;margin:36px 0 14px}article h3{font-size:19px;line-height:1.5;margin:28px 0 12px}
article p{margin:0 0 18px}article ul,article ol{padding-left:1.5em;margin:0 0 20px}article li{margin:6px 0}
article blockquote{margin:22px 0;padding:2px 0 2px 18px;border-left:3px solid var(--line);color:var(--muted)}
article a{color:var(--link);text-decoration:none;border-bottom:1px solid color-mix(in srgb,var(--link) 35%,transparent)}
article img{display:block;max-width:100%;height:auto;margin:24px auto;border-radius:8px}
article pre{overflow-x:auto;margin:22px 0;padding:16px;border-radius:10px;background:var(--code);line-height:1.6;font-size:14px;-webkit-overflow-scrolling:touch}
article code{font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono",monospace;font-size:.9em;background:var(--code);padding:.15em .35em;border-radius:4px}
article pre code{padding:0;background:transparent;font-size:inherit}
article table{display:block;width:100%;overflow-x:auto;border-collapse:collapse;margin:22px 0}article th,article td{border:1px solid var(--line);padding:8px 12px;text-align:left}
article hr{border:0;border-top:1px solid var(--line);margin:34px 0}
.fallback{white-space:pre-wrap;word-break:break-word}
.render-warning{color:var(--warn);font-size:14px}
footer{margin-top:48px;padding-top:18px;border-top:1px solid var(--line);color:var(--muted);font-size:13px}
@media(max-width:560px){main{padding:30px 18px 56px}article{font-size:16.5px}article h1{font-size:27px}article h2{font-size:21px}}
</style>
</head>
<body>
<main>
<header><div class="meta"><span>2026-09-01 10:20 +0800</span><span class="dot">·</span><span>文章</span></div></header>
<article><h1>OpenClaw Docker 部署维护指南:记住「2 个主配置 + 3 个辅助文件」</h1>
<p dir="auto">Docker 部署 OpenClaw 后,日常维护只需抓住核心文件结构。本文把功能配置、密钥配置、常见修改场景和常用命令一次讲清。</p>
<h2>核心文件结构</h2>
<p dir="auto">当前真正最重要的是:</p>
<div><pre><code>/root/local-app/openclaw-walter/
│
├── .env ← 密钥、环境变量
├── docker-compose.yml ← Docker部署层,平时基本不改
│
├── data/openclaw/
│ └── openclaw.json ← ★ OpenClaw 最核心配置文件
│
├── config/
│ └── .npmrc ← npm国内源
│
└── INSTALL_INFO.txt ← 安装信息/端口/Token
</code></pre></div><p dir="auto">OpenClaw 官方从 <code>~/.openclaw/openclaw.json</code> 读取主配置;在 Docker 映射里,对应宿主机就是 <code>/root/local-app/openclaw-walter/data/openclaw/openclaw.json</code>。</p>
<h3>主要管这两个</h3>
<p dir="auto"><strong>1. <code>openclaw.json</code> —— 功能配置</strong></p>
<p dir="auto">负责:LLM、Hindsight、Browser、微信插件启停、Agent、模型选择、Skill、工具权限、Gateway、MCP,即绝大多数功能配置。</p>
<p dir="auto"><strong>2. <code>.env</code> —— 密钥配置</strong></p>
<p dir="auto">负责:Gateway Token、LLM API Key、Hindsight Token、npm Registry、Docker 环境变量。</p>
<p dir="auto">原则:</p>
<blockquote>
<p dir="auto"><strong>功能参数进 <code>openclaw.json</code>,密码 / API Key 尽量进 <code>.env</code>。</strong></p>
</blockquote>
<p dir="auto">这样备份、迁移、安全性都会清晰很多。</p>
<h2>一、Hindsight 后续怎么改</h2>
<p dir="auto">Hindsight 的主要配置会进入 <code>data/openclaw/openclaw.json</code>,大致结构:</p>
<div><pre><code><span class="p">{</span>
<span class="nt">&#34;plugins&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;entries&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;hindsight-openclaw&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;enabled&#34;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nt">&#34;config&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;hindsightApiUrl&#34;</span><span class="p">:</span> <span class="s2">&#34;http://t.stoneji.cc:18888&#34;</span><span class="p">,</span>
<span class="nt">&#34;dynamicBankId&#34;</span><span class="p">:</span> <span class="kc">false</span><span class="p">,</span>
<span class="nt">&#34;bankId&#34;</span><span class="p">:</span> <span class="s2">&#34;walter&#34;</span><span class="p">,</span>
<span class="nt">&#34;autoRecall&#34;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nt">&#34;autoRetain&#34;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nt">&#34;recallBudget&#34;</span><span class="p">:</span> <span class="s2">&#34;mid&#34;</span><span class="p">,</span>
<span class="nt">&#34;recallMaxTokens&#34;</span><span class="p">:</span> <span class="mi">1024</span><span class="p">,</span>
<span class="nt">&#34;enableKnowledgeTools&#34;</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div><h3>推荐修改方式</h3>
<p dir="auto"><strong>不要直接 vim JSON</strong>,用命令改:</p>
<div><pre><code><span class="nb">cd</span> /root/local-app/openclaw-walter
<span class="c1"># 查看</span>
./openclaw.sh config get plugins.entries.hindsight-openclaw
<span class="c1"># 改 Hindsight 地址</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> plugins.entries.hindsight-openclaw.config.hindsightApiUrl <span class="se">\
</span> <span class="s2">&#34;http://新的地址:18888&#34;</span>
<span class="c1"># 改 Bank</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> plugins.entries.hindsight-openclaw.config.bankId <span class="se">\
</span> <span class="s2">&#34;walter&#34;</span>
<span class="c1"># 开启 Recall</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> plugins.entries.hindsight-openclaw.config.autoRecall <span class="se">\
</span> <span class="nb">true</span> --strict-json
<span class="c1"># 开启 Retain</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> plugins.entries.hindsight-openclaw.config.autoRetain <span class="se">\
</span> <span class="nb">true</span> --strict-json
<span class="c1"># Recall 深度</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> plugins.entries.hindsight-openclaw.config.recallBudget <span class="se">\
</span> <span class="s2">&#34;mid&#34;</span>
</code></pre></div><p dir="auto">Recall 深度可选:<code>low</code>(快、省)、<code>mid</code>(均衡,推荐)、<code>high</code>(更深入、更慢)。</p>
<h3>Hindsight Token 怎么改</h3>
<p dir="auto">敏感信息放 <code>.env</code>:</p>
<div><pre><code>nano /root/local-app/openclaw-walter/.env
</code></pre></div><div><pre><code><span class="na">HINDSIGHT_API_TOKEN</span><span class="o">=</span><span class="s">你的token</span>
</code></pre></div><p dir="auto"><code>.env</code> 是 Docker 启动时注入的,改完后必须用 <code>--force-recreate</code>:</p>
<div><pre><code>docker compose up -d --force-recreate openclaw-gateway
</code></pre></div><p dir="auto">不是普通 restart。</p>
<h2>二、LLM 后续怎么改</h2>
<p dir="auto">已专门生成了配置脚本 <code>/root/local-app/openclaw-walter/configure-responses-llm.sh</code>,第一次配置直接跑:</p>
<div><pre><code><span class="nb">cd</span> /root/local-app/openclaw-walter
./configure-responses-llm.sh
</code></pre></div><p dir="auto">它配置两部分:</p>
<p dir="auto"><strong><code>.env</code> 保存:</strong></p>
<div><pre><code><span class="na">OPENCLAW_CUSTOM_LLM_API_KEY</span><span class="o">=</span><span class="s">sk-xxxx</span>
</code></pre></div><p dir="auto"><strong><code>openclaw.json</code> 保存:</strong></p>
<div><pre><code><span class="p">{</span>
<span class="nt">&#34;models&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;mode&#34;</span><span class="p">:</span> <span class="s2">&#34;merge&#34;</span><span class="p">,</span>
<span class="nt">&#34;providers&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;custom&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;baseUrl&#34;</span><span class="p">:</span> <span class="s2">&#34;https://api.xxx.com/v1&#34;</span><span class="p">,</span>
<span class="nt">&#34;api&#34;</span><span class="p">:</span> <span class="s2">&#34;openai-responses&#34;</span><span class="p">,</span>
<span class="nt">&#34;apiKey&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;source&#34;</span><span class="p">:</span> <span class="s2">&#34;env&#34;</span><span class="p">,</span>
<span class="nt">&#34;provider&#34;</span><span class="p">:</span> <span class="s2">&#34;default&#34;</span><span class="p">,</span>
<span class="nt">&#34;id&#34;</span><span class="p">:</span> <span class="s2">&#34;OPENCLAW_CUSTOM_LLM_API_KEY&#34;</span>
<span class="p">},</span>
<span class="nt">&#34;timeoutSeconds&#34;</span><span class="p">:</span> <span class="mi">300</span><span class="p">,</span>
<span class="nt">&#34;models&#34;</span><span class="p">:</span> <span class="p">[</span>
<span class="p">{</span>
<span class="nt">&#34;id&#34;</span><span class="p">:</span> <span class="s2">&#34;gpt-xxx&#34;</span><span class="p">,</span>
<span class="nt">&#34;name&#34;</span><span class="p">:</span> <span class="s2">&#34;gpt-xxx&#34;</span><span class="p">,</span>
<span class="nt">&#34;reasoning&#34;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nt">&#34;input&#34;</span><span class="p">:</span> <span class="p">[</span><span class="s2">&#34;text&#34;</span><span class="p">,</span> <span class="s2">&#34;image&#34;</span><span class="p">],</span>
<span class="nt">&#34;contextWindow&#34;</span><span class="p">:</span> <span class="mi">200000</span><span class="p">,</span>
<span class="nt">&#34;maxTokens&#34;</span><span class="p">:</span> <span class="mi">32768</span>
<span class="p">}</span>
<span class="p">]</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="nt">&#34;agents&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;defaults&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;model&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;primary&#34;</span><span class="p">:</span> <span class="s2">&#34;custom/gpt-xxx&#34;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div><p dir="auto">通过 <code>models.providers</code> 配置自定义 Base URL,用 <code>api: openai-responses</code> 指定 Responses API(前提是上游真的支持 <code>/v1/responses</code>)。</p>
<h2>三、只改 LLM 地址</h2>
<p dir="auto">不用重跑配置器:</p>
<div><pre><code>./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> models.providers.custom.baseUrl <span class="se">\
</span> <span class="s2">&#34;https://api.b.com/v1&#34;</span>
docker compose restart openclaw-gateway
</code></pre></div><h2>四、换 API Key</h2>
<div><pre><code>nano .env
<span class="c1"># OPENCLAW_CUSTOM_LLM_API_KEY=sk-old → sk-new</span>
docker compose up -d --force-recreate openclaw-gateway
</code></pre></div><p dir="auto">传递链路:</p>
<div><pre><code>.env → Docker Environment → SecretRef → OpenClaw
</code></pre></div><p dir="auto">不要把 API Key 明文写进 <code>openclaw.json</code>。</p>
<h2>五、切换默认模型</h2>
<div><pre><code><span class="c1"># 查看</span>
./openclaw.sh models list
<span class="c1"># 切换</span>
./openclaw.sh models <span class="nb">set</span> custom/gpt-5.6-sol
<span class="c1"># 或直接改配置</span>
./openclaw.sh config <span class="nb">set</span> <span class="se">\
</span> agents.defaults.model.primary <span class="se">\
</span> <span class="s2">&#34;custom/gpt-5.6-sol&#34;</span>
</code></pre></div><p dir="auto">模型引用统一使用 <code>provider/model</code> 格式,例如:</p>
<div><pre><code>custom/gpt-5.6-sol
deepseek/deepseek-v3
dashscope/qwen3-max
</code></pre></div><h2>六、建议配置两个 LLM Provider</h2>
<div><pre><code><span class="p">{</span>
<span class="nt">&#34;models&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;providers&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;main&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;baseUrl&#34;</span><span class="p">:</span> <span class="s2">&#34;https://api.xxx.com/v1&#34;</span><span class="p">,</span>
<span class="nt">&#34;api&#34;</span><span class="p">:</span> <span class="s2">&#34;openai-responses&#34;</span>
<span class="p">},</span>
<span class="nt">&#34;deepseek&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;baseUrl&#34;</span><span class="p">:</span> <span class="s2">&#34;https://api.deepseek.com/v1&#34;</span><span class="p">,</span>
<span class="nt">&#34;api&#34;</span><span class="p">:</span> <span class="s2">&#34;openai-completions&#34;</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div><div><pre><code>main/gpt-5.6-sol
deepseek/deepseek-chat
</code></pre></div><p dir="auto">主模型:<code>./openclaw.sh models set main/gpt-5.6-sol</code></p>
<h2>七、微信:插件启停与账号</h2>
<p dir="auto"><strong>插件启停</strong>在 <code>openclaw.json</code>:</p>
<div><pre><code><span class="p">{</span>
<span class="nt">&#34;plugins&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;entries&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;openclaw-weixin&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;enabled&#34;</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div><div><pre><code><span class="c1"># 查看</span>
./openclaw.sh config get plugins.entries.openclaw-weixin
<span class="c1"># 启用 / 禁用</span>
./openclaw.sh config <span class="nb">set</span> plugins.entries.openclaw-weixin.enabled <span class="nb">true</span> --strict-json
./openclaw.sh config <span class="nb">set</span> plugins.entries.openclaw-weixin.enabled <span class="nb">false</span> --strict-json
</code></pre></div><p dir="auto"><strong>微信账号 Token 不要手工编辑</strong>。登录用:</p>
<div><pre><code>./wechat-login.sh
</code></pre></div><p dir="auto">本质执行 <code>openclaw channels login --channel openclaw-weixin</code>。扫码成功后,插件自动把账号凭据写入 <code>~/.openclaw</code>(即宿主机 <code>/root/local-app/openclaw-walter/data/openclaw/</code>)。重新登录直接再跑脚本即可。</p>
<p dir="auto"><strong>多账号</strong>:再运行一次 <code>./wechat-login.sh</code> 添加第二账号,并建议:</p>
<div><pre><code>./openclaw.sh config <span class="nb">set</span> session.dmScope per-account-channel-peer
</code></pre></div><p dir="auto">这样微信账号 A/B 的用户会话不会混。</p>
<h2>八、Browser 配置</h2>
<div><pre><code><span class="p">{</span>
<span class="nt">&#34;browser&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;enabled&#34;</span><span class="p">:</span> <span class="kc">true</span><span class="p">,</span>
<span class="nt">&#34;defaultProfile&#34;</span><span class="p">:</span> <span class="s2">&#34;openclaw&#34;</span><span class="p">,</span>
<span class="nt">&#34;headless&#34;</span><span class="p">:</span> <span class="kc">true</span>
<span class="p">}</span>
<span class="p">}</span>
</code></pre></div><div><pre><code>./openclaw.sh config get browser
./browser-test.sh
</code></pre></div><h2>九、docker-compose.yml 什么时候才需要改</h2>
<p dir="auto">只管「基础设施」:端口、Volume、网络。端口实际来自 <code>.env</code> 的 <code>OPENCLAW_HOST_PORT=18789</code>,大部分情况只改 <code>.env</code> 即可,无需动 compose。</p>
<h2>十、<code>.npmrc</code> 基本不用碰</h2>
<p dir="auto">位置 <code>/root/local-app/openclaw-walter/config/.npmrc</code>,如:</p>
<div><pre><code><span class="na">registry</span><span class="o">=</span><span class="s">https://registry.npmmirror.com/</span>
</code></pre></div><p dir="auto">只有 npm 镜像挂了才改。</p>
<h2>十一、建议不要直接编辑 openclaw.json</h2>
<p dir="auto">虽然可以 <code>nano data/openclaw/openclaw.json</code>,但官方更推荐:</p>
<div><pre><code>openclaw config get
openclaw config <span class="nb">set</span>
openclaw config validate
</code></pre></div><p dir="auto">自定义 Provider 增量更新用 <code>config set ... --merge</code>,减少误覆盖风险。</p>
<p dir="auto">日常固定习惯:</p>
<div><pre><code><span class="nb">cd</span> /root/local-app/openclaw-walter
<span class="c1"># 查看</span>
./openclaw.sh config get xxx
<span class="c1"># 修改</span>
./openclaw.sh config <span class="nb">set</span> xxx value
<span class="c1"># 验证</span>
./openclaw.sh config validate
<span class="c1"># 重启</span>
docker compose restart openclaw-gateway
</code></pre></div><h2>十二、记忆规则</h2>
<div><pre><code> OpenClaw 配置
│
┌───────────┴───────────┐
│ │
非敏感配置 密钥
│ │
▼ ▼
openclaw.json .env
│ │
Hindsight参数 LLM API KEY
LLM Provider Hindsight Token
默认模型 Gateway Token
Browser
Plugin开关
Agent
MCP
</code></pre></div><p dir="auto">再往外:</p>
<div><pre><code>docker-compose.yml
↓
只负责 Docker / 端口 / Volume / 网络
.npmrc
↓
只负责 npm / pnpm 下载源
</code></pre></div><h2>十三、最常用的 10 条命令</h2>
<div><pre><code><span class="nb">cd</span> /root/local-app/openclaw-walter
<span class="c1"># 整体状态</span>
./status.sh
<span class="c1"># OpenClaw 日志</span>
./logs.sh
<span class="c1"># 检查配置</span>
./openclaw.sh config validate
<span class="c1"># 看 Hindsight</span>
./openclaw.sh config get plugins.entries.hindsight-openclaw
<span class="c1"># 看 LLM</span>
./openclaw.sh config get models
<span class="c1"># 看默认模型</span>
./openclaw.sh config get agents.defaults.model
<span class="c1"># 模型列表</span>
./openclaw.sh models list
<span class="c1"># 微信状态</span>
./openclaw.sh channels status --probe
<span class="c1"># 微信重新登录</span>
./wechat-login.sh
<span class="c1"># Browser</span>
./browser-test.sh
</code></pre></div><p dir="auto"><strong>总结</strong>:长期维护的核心文件就是 <code>data/openclaw/openclaw.json</code>,日常通过 <code>./openclaw.sh config set</code> 修改;<code>.env</code> 只在改 API Key、Token 这些秘密时动。这样后续增加 Hindsight、微信、WPS MCP、Radicale/ntfy MCP、多个 LLM Provider,都不会越来越乱。</p>
<h2>参考</h2>
<ul dir="auto">
<li><a href="https://docs.openclaw.ai/zh-CN/help/faq" rel="nofollow">OpenClaw 常见问题</a></li>
<li><a href="https://github.com/vectorize-io/hindsight/blob/main/hindsight-docs/docs-integrations/codex.md" rel="nofollow">Hindsight 集成文档</a></li>
<li><a href="https://docs.openclaw.ai/zh-CN/gateway/config-tools" rel="nofollow">OpenClaw 配置工具与自定义提供商</a></li>
<li><a href="https://docs.openclaw.ai/zh-CN/help/faq-models" rel="nofollow">OpenClaw 模型与身份验证 FAQ</a></li>
<li><a href="https://docs.openclaw.ai/zh-CN/channels/wechat" rel="nofollow">OpenClaw 微信频道</a></li>
</ul>
</article>
<footer>公开分享页面 · Markdown 与 HTML 均保存在版本化仓库</footer>
</main>
</body>
</html>