442 lines
9.8 KiB
Markdown
442 lines
9.8 KiB
Markdown
# OpenClaw Docker 部署维护指南：记住「2 个主配置 + 3 个辅助文件」
|
||
|
||
Docker 部署 OpenClaw 后，日常维护只需抓住核心文件结构。本文把功能配置、密钥配置、常见修改场景和常用命令一次讲清。
|
||
|
||
## 核心文件结构
|
||
|
||
当前真正最重要的是：
|
||
|
||
```text
|
||
/root/local-app/openclaw-walter/
|
||
│
|
||
├── .env ← 密钥、环境变量
|
||
├── docker-compose.yml ← Docker部署层，平时基本不改
|
||
│
|
||
├── data/openclaw/
|
||
│ └── openclaw.json ← ★ OpenClaw 最核心配置文件
|
||
│
|
||
├── config/
|
||
│ └── .npmrc ← npm国内源
|
||
│
|
||
└── INSTALL_INFO.txt ← 安装信息/端口/Token
|
||
```
|
||
|
||
OpenClaw 官方从 `~/.openclaw/openclaw.json` 读取主配置；在 Docker 映射里，对应宿主机就是 `/root/local-app/openclaw-walter/data/openclaw/openclaw.json`。
|
||
|
||
### 主要管这两个
|
||
|
||
**1. `openclaw.json` —— 功能配置**
|
||
|
||
负责：LLM、Hindsight、Browser、微信插件启停、Agent、模型选择、Skill、工具权限、Gateway、MCP，即绝大多数功能配置。
|
||
|
||
**2. `.env` —— 密钥配置**
|
||
|
||
负责：Gateway Token、LLM API Key、Hindsight Token、npm Registry、Docker 环境变量。
|
||
|
||
原则：
|
||
|
||
> **功能参数进 `openclaw.json`，密码 / API Key 尽量进 `.env`。**
|
||
|
||
这样备份、迁移、安全性都会清晰很多。
|
||
|
||
## 一、Hindsight 后续怎么改
|
||
|
||
Hindsight 的主要配置会进入 `data/openclaw/openclaw.json`，大致结构：
|
||
|
||
```json
|
||
{
|
||
"plugins": {
|
||
"entries": {
|
||
"hindsight-openclaw": {
|
||
"enabled": true,
|
||
"config": {
|
||
"hindsightApiUrl": "http://t.stoneji.cc:18888",
|
||
"dynamicBankId": false,
|
||
"bankId": "walter",
|
||
"autoRecall": true,
|
||
"autoRetain": true,
|
||
"recallBudget": "mid",
|
||
"recallMaxTokens": 1024,
|
||
"enableKnowledgeTools": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
### 推荐修改方式
|
||
|
||
**不要直接 vim JSON**，用命令改：
|
||
|
||
```bash
|
||
cd /root/local-app/openclaw-walter
|
||
|
||
# 查看
|
||
./openclaw.sh config get plugins.entries.hindsight-openclaw
|
||
|
||
# 改 Hindsight 地址
|
||
./openclaw.sh config set \
|
||
plugins.entries.hindsight-openclaw.config.hindsightApiUrl \
|
||
"http://新的地址:18888"
|
||
|
||
# 改 Bank
|
||
./openclaw.sh config set \
|
||
plugins.entries.hindsight-openclaw.config.bankId \
|
||
"walter"
|
||
|
||
# 开启 Recall
|
||
./openclaw.sh config set \
|
||
plugins.entries.hindsight-openclaw.config.autoRecall \
|
||
true --strict-json
|
||
|
||
# 开启 Retain
|
||
./openclaw.sh config set \
|
||
plugins.entries.hindsight-openclaw.config.autoRetain \
|
||
true --strict-json
|
||
|
||
# Recall 深度
|
||
./openclaw.sh config set \
|
||
plugins.entries.hindsight-openclaw.config.recallBudget \
|
||
"mid"
|
||
```
|
||
|
||
Recall 深度可选：`low`（快、省）、`mid`（均衡，推荐）、`high`（更深入、更慢）。
|
||
|
||
### Hindsight Token 怎么改
|
||
|
||
敏感信息放 `.env`：
|
||
|
||
```bash
|
||
nano /root/local-app/openclaw-walter/.env
|
||
```
|
||
|
||
```ini
|
||
HINDSIGHT_API_TOKEN=你的token
|
||
```
|
||
|
||
`.env` 是 Docker 启动时注入的，改完后必须用 `--force-recreate`：
|
||
|
||
```bash
|
||
docker compose up -d --force-recreate openclaw-gateway
|
||
```
|
||
|
||
不是普通 restart。
|
||
|
||
## 二、LLM 后续怎么改
|
||
|
||
已专门生成了配置脚本 `/root/local-app/openclaw-walter/configure-responses-llm.sh`，第一次配置直接跑：
|
||
|
||
```bash
|
||
cd /root/local-app/openclaw-walter
|
||
./configure-responses-llm.sh
|
||
```
|
||
|
||
它配置两部分：
|
||
|
||
**`.env` 保存：**
|
||
|
||
```ini
|
||
OPENCLAW_CUSTOM_LLM_API_KEY=sk-xxxx
|
||
```
|
||
|
||
**`openclaw.json` 保存：**
|
||
|
||
```json
|
||
{
|
||
"models": {
|
||
"mode": "merge",
|
||
"providers": {
|
||
"custom": {
|
||
"baseUrl": "https://api.xxx.com/v1",
|
||
"api": "openai-responses",
|
||
"apiKey": {
|
||
"source": "env",
|
||
"provider": "default",
|
||
"id": "OPENCLAW_CUSTOM_LLM_API_KEY"
|
||
},
|
||
"timeoutSeconds": 300,
|
||
"models": [
|
||
{
|
||
"id": "gpt-xxx",
|
||
"name": "gpt-xxx",
|
||
"reasoning": true,
|
||
"input": ["text", "image"],
|
||
"contextWindow": 200000,
|
||
"maxTokens": 32768
|
||
}
|
||
]
|
||
}
|
||
}
|
||
},
|
||
"agents": {
|
||
"defaults": {
|
||
"model": {
|
||
"primary": "custom/gpt-xxx"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
通过 `models.providers` 配置自定义 Base URL，用 `api: openai-responses` 指定 Responses API（前提是上游真的支持 `/v1/responses`）。
|
||
|
||
## 三、只改 LLM 地址
|
||
|
||
不用重跑配置器：
|
||
|
||
```bash
|
||
./openclaw.sh config set \
|
||
models.providers.custom.baseUrl \
|
||
"https://api.b.com/v1"
|
||
|
||
docker compose restart openclaw-gateway
|
||
```
|
||
|
||
## 四、换 API Key
|
||
|
||
```bash
|
||
nano .env
|
||
# OPENCLAW_CUSTOM_LLM_API_KEY=sk-old → sk-new
|
||
|
||
docker compose up -d --force-recreate openclaw-gateway
|
||
```
|
||
|
||
传递链路：
|
||
|
||
```text
|
||
.env → Docker Environment → SecretRef → OpenClaw
|
||
```
|
||
|
||
不要把 API Key 明文写进 `openclaw.json`。
|
||
|
||
## 五、切换默认模型
|
||
|
||
```bash
|
||
# 查看
|
||
./openclaw.sh models list
|
||
|
||
# 切换
|
||
./openclaw.sh models set custom/gpt-5.6-sol
|
||
|
||
# 或直接改配置
|
||
./openclaw.sh config set \
|
||
agents.defaults.model.primary \
|
||
"custom/gpt-5.6-sol"
|
||
```
|
||
|
||
模型引用统一使用 `provider/model` 格式，例如：
|
||
|
||
```text
|
||
custom/gpt-5.6-sol
|
||
deepseek/deepseek-v3
|
||
dashscope/qwen3-max
|
||
```
|
||
|
||
## 六、建议配置两个 LLM Provider
|
||
|
||
```json
|
||
{
|
||
"models": {
|
||
"providers": {
|
||
"main": {
|
||
"baseUrl": "https://api.xxx.com/v1",
|
||
"api": "openai-responses"
|
||
},
|
||
"deepseek": {
|
||
"baseUrl": "https://api.deepseek.com/v1",
|
||
"api": "openai-completions"
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
```text
|
||
main/gpt-5.6-sol
|
||
deepseek/deepseek-chat
|
||
```
|
||
|
||
主模型：`./openclaw.sh models set main/gpt-5.6-sol`
|
||
|
||
## 七、微信：插件启停与账号
|
||
|
||
**插件启停**在 `openclaw.json`：
|
||
|
||
```json
|
||
{
|
||
"plugins": {
|
||
"entries": {
|
||
"openclaw-weixin": {
|
||
"enabled": true
|
||
}
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
# 查看
|
||
./openclaw.sh config get plugins.entries.openclaw-weixin
|
||
|
||
# 启用 / 禁用
|
||
./openclaw.sh config set plugins.entries.openclaw-weixin.enabled true --strict-json
|
||
./openclaw.sh config set plugins.entries.openclaw-weixin.enabled false --strict-json
|
||
```
|
||
|
||
**微信账号 Token 不要手工编辑**。登录用：
|
||
|
||
```bash
|
||
./wechat-login.sh
|
||
```
|
||
|
||
本质执行 `openclaw channels login --channel openclaw-weixin`。扫码成功后，插件自动把账号凭据写入 `~/.openclaw`（即宿主机 `/root/local-app/openclaw-walter/data/openclaw/`）。重新登录直接再跑脚本即可。
|
||
|
||
**多账号**：再运行一次 `./wechat-login.sh` 添加第二账号，并建议：
|
||
|
||
```bash
|
||
./openclaw.sh config set session.dmScope per-account-channel-peer
|
||
```
|
||
|
||
这样微信账号 A/B 的用户会话不会混。
|
||
|
||
## 八、Browser 配置
|
||
|
||
```json
|
||
{
|
||
"browser": {
|
||
"enabled": true,
|
||
"defaultProfile": "openclaw",
|
||
"headless": true
|
||
}
|
||
}
|
||
```
|
||
|
||
```bash
|
||
./openclaw.sh config get browser
|
||
./browser-test.sh
|
||
```
|
||
|
||
## 九、docker-compose.yml 什么时候才需要改
|
||
|
||
只管「基础设施」：端口、Volume、网络。端口实际来自 `.env` 的 `OPENCLAW_HOST_PORT=18789`，大部分情况只改 `.env` 即可，无需动 compose。
|
||
|
||
## 十、`.npmrc` 基本不用碰
|
||
|
||
位置 `/root/local-app/openclaw-walter/config/.npmrc`，如：
|
||
|
||
```ini
|
||
registry=https://registry.npmmirror.com/
|
||
```
|
||
|
||
只有 npm 镜像挂了才改。
|
||
|
||
## 十一、建议不要直接编辑 openclaw.json
|
||
|
||
虽然可以 `nano data/openclaw/openclaw.json`，但官方更推荐：
|
||
|
||
```bash
|
||
openclaw config get
|
||
openclaw config set
|
||
openclaw config validate
|
||
```
|
||
|
||
自定义 Provider 增量更新用 `config set ... --merge`，减少误覆盖风险。
|
||
|
||
日常固定习惯：
|
||
|
||
```bash
|
||
cd /root/local-app/openclaw-walter
|
||
|
||
# 查看
|
||
./openclaw.sh config get xxx
|
||
|
||
# 修改
|
||
./openclaw.sh config set xxx value
|
||
|
||
# 验证
|
||
./openclaw.sh config validate
|
||
|
||
# 重启
|
||
docker compose restart openclaw-gateway
|
||
```
|
||
|
||
## 十二、记忆规则
|
||
|
||
```text
|
||
OpenClaw 配置
|
||
│
|
||
┌───────────┴───────────┐
|
||
│ │
|
||
非敏感配置 密钥
|
||
│ │
|
||
▼ ▼
|
||
openclaw.json .env
|
||
│ │
|
||
Hindsight参数 LLM API KEY
|
||
LLM Provider Hindsight Token
|
||
默认模型 Gateway Token
|
||
Browser
|
||
Plugin开关
|
||
Agent
|
||
MCP
|
||
```
|
||
|
||
再往外：
|
||
|
||
```text
|
||
docker-compose.yml
|
||
↓
|
||
只负责 Docker / 端口 / Volume / 网络
|
||
|
||
.npmrc
|
||
↓
|
||
只负责 npm / pnpm 下载源
|
||
```
|
||
|
||
## 十三、最常用的 10 条命令
|
||
|
||
```bash
|
||
cd /root/local-app/openclaw-walter
|
||
|
||
# 整体状态
|
||
./status.sh
|
||
|
||
# OpenClaw 日志
|
||
./logs.sh
|
||
|
||
# 检查配置
|
||
./openclaw.sh config validate
|
||
|
||
# 看 Hindsight
|
||
./openclaw.sh config get plugins.entries.hindsight-openclaw
|
||
|
||
# 看 LLM
|
||
./openclaw.sh config get models
|
||
|
||
# 看默认模型
|
||
./openclaw.sh config get agents.defaults.model
|
||
|
||
# 模型列表
|
||
./openclaw.sh models list
|
||
|
||
# 微信状态
|
||
./openclaw.sh channels status --probe
|
||
|
||
# 微信重新登录
|
||
./wechat-login.sh
|
||
|
||
# Browser
|
||
./browser-test.sh
|
||
```
|
||
|
||
**总结**：长期维护的核心文件就是 `data/openclaw/openclaw.json`，日常通过 `./openclaw.sh config set` 修改；`.env` 只在改 API Key、Token 这些秘密时动。这样后续增加 Hindsight、微信、WPS MCP、Radicale/ntfy MCP、多个 LLM Provider，都不会越来越乱。
|
||
|
||
## 参考
|
||
|
||
- [OpenClaw 常见问题](https://docs.openclaw.ai/zh-CN/help/faq)
|
||
- [Hindsight 集成文档](https://github.com/vectorize-io/hindsight/blob/main/hindsight-docs/docs-integrations/codex.md)
|
||
- [OpenClaw 配置工具与自定义提供商](https://docs.openclaw.ai/zh-CN/gateway/config-tools)
|
||
- [OpenClaw 模型与身份验证 FAQ](https://docs.openclaw.ai/zh-CN/help/faq-models)
|
||
- [OpenClaw 微信频道](https://docs.openclaw.ai/zh-CN/channels/wechat)
|