publish: OpenClaw Docker 部署维护指南：2 个主配置 + 3 个辅助文件
This commit is contained in:
@@ -0,0 +1,441 @@
|
||||
# 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)
|
||||
Reference in New Issue
Block a user