OpenClaw CLI 和配置文件參考完整指南
我要評(píng)論OpenClaw 的配置完全通過(guò)一個(gè) JSON5 文件~/.openclaw/openclaw.json和一個(gè)包含 100 多個(gè)子命令的 CLI 來(lái)實(shí)現(xiàn)。然而，這兩者都沒(méi)有統(tǒng)一的完整文檔。官方 CLI 參考文檔列出了命令樹(shù)；配置參考文檔解釋了各個(gè)字段；但連接它們的實(shí)用模式、模式嚴(yán)格性、熱重載行為和配置層級(jí)結(jié)構(gòu)等方面的注意事項(xiàng)，都分散在 GitHub issues、社區(qū)運(yùn)行手冊(cè)和生產(chǎn)環(huán)境的復(fù)盤(pán)報(bào)告中。
本指南全面涵蓋了這兩方面。首先介紹配置文件：格式、結(jié)構(gòu)以及每個(gè)主要部分的示例。然后介紹命令行界面 (CLI)：按工作流程而非字母順序組織，方便您快速找到網(wǎng)關(guān)管理、通道設(shè)置、診斷和自動(dòng)化所需的內(nèi)容。最后介紹環(huán)境變量、其解析順序以及如何在版本控制下安全地管理配置。
openclaw.json 配置文件
文件格式、位置和驗(yàn)證規(guī)則
配置文件采用JSON5 格式，而非純 JSON。這意味著注釋（` // like this&`）、尾隨逗號(hào)和未加引號(hào)的鍵值都是有效的。該文件默認(rèn)位于 `/etc/config/ ~/.openclaw/openclaw.jsonconfig`。您可以使用OPENCLAW_CONFIG_PATH環(huán)境變量或--profile <name>CLI 標(biāo)志覆蓋其默認(rèn)位置，這將把所有狀態(tài)隔離到一個(gè)單獨(dú)的目錄中，這對(duì)于測(cè)試或運(yùn)行多個(gè)隔離實(shí)例非常有用。
Zod 會(huì)在啟動(dòng)時(shí)強(qiáng)制執(zhí)行架構(gòu)驗(yàn)證。未知鍵會(huì)導(dǎo)致網(wǎng)關(guān)拒絕啟動(dòng)。沒(méi)有警告模式，也沒(méi)有優(yōu)雅降級(jí)：如果您添加了架構(gòu)中不存在的鍵，網(wǎng)關(guān)將無(wú)法啟動(dòng)，并且錯(cuò)誤消息會(huì)指向錯(cuò)誤的鍵。這是在手動(dòng)編輯文件之前必須了解的最重要的一點(diǎn)。安全的編輯工作流程：
# 1. Back up first — always cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak # 2. Edit the file # 3. Validate JSON5 syntax cat ~/.openclaw/openclaw.json | python3 -m json.tool # 4. Validate schema and fix any issues openclaw doctor --fix
網(wǎng)關(guān)會(huì)監(jiān)視文件更改，并在無(wú)需重啟的情況下熱重載大多數(shù)設(shè)置。“大多數(shù)”這個(gè)詞很重要——請(qǐng)參閱下面的熱重載部分，了解哪些更改需要重啟，哪些不需要，因?yàn)樵谏a(chǎn)環(huán)境中，靜默失敗的熱重載常常會(huì)造成混亂。
頂層配置結(jié)構(gòu)
所有頂級(jí)部分的完整概覽：
{
// Written by the wizard — don't edit manually
meta: { lastTouchedVersion: "...", lastTouchedAt: "..." },
gateway: { ... }, // Port, bind address, auth token
update: { channel: "stable" }, // stable | beta | dev
env: { shellEnv: { enabled: true }, vars: { KEY: "value" } },
agents: { defaults: { ... }, list: [ ... ] }, // Agent config + overrides
models: { mode: "merge", providers: { ... } }, // LLM providers
auth: { profiles: { ... }, order: { ... } }, // Provider failover
channels: { telegram: { ... }, discord: { ... } }, // Messaging channels
session: { dmScope: "per-channel-peer", reset: { ... } },
bindings: [ { agentId: "...", match: { ... } } ], // Multi-agent routing
cron: { enabled: true, maxConcurrentRuns: 2 },
tools: { web: { search: { provider: "brave", apiKey: "..." } } },
sandbox: { mode: "non-main", docker: { ... } },
logging: { level: "info", consoleLevel: "warn" },
skills: { install: { nodeManager: "pnpm" } },
}網(wǎng)關(guān)部分
控制網(wǎng)關(guān)進(jìn)程的綁定、身份驗(yàn)證和重新加載方式：
gateway: {
port: 18789,
mode: "local", // local | cloud
bind: "loopback", // loopback = 127.0.0.1 only (recommended)
// all = 0.0.0.0 (requires auth token)
auth: {
mode: "token",
token: "your-generated-token",
allowTailscale: true, // Tailscale IPs bypass token check
},
controlUi: {
enabled: true,
dangerouslyDisableDeviceAuth: false, // never true on shared hosts
},
reload: "hybrid", // hot | hybrid | restart
}bind: "loopback"務(wù)必在 VPS 部署中使用此功能。bind: "all"如果沒(méi)有強(qiáng)身份驗(yàn)證令牌，網(wǎng)關(guān)將暴露在互聯(lián)網(wǎng)上。暴露在公共 IP 上的 OpenClaw 網(wǎng)關(guān)會(huì)導(dǎo)致 API 密鑰、OAuth 令牌和會(huì)話歷史記錄泄露。如果沒(méi)有身份驗(yàn)證令牌，網(wǎng)關(guān)將拒絕綁定到非環(huán)回地址。有關(guān)反向代理設(shè)置，請(qǐng)參閱VPS 安全指南。
該reload字段控制熱重載行為。"hybrid"盡可能實(shí)時(shí)應(yīng)用更改，僅在必要時(shí)重啟。gateway.reload還有g(shù)ateway.remote兩個(gè)字段在更改時(shí)不會(huì)觸發(fā)重新加載——如果您更改了其中任何一個(gè)字段，請(qǐng)手動(dòng)重啟網(wǎng)關(guān)。
代理部分：默認(rèn)值和每個(gè)代理的自定義設(shè)置
代理部分采用“默認(rèn)值+覆蓋”模式，agents.defaults為每個(gè)代理設(shè)置基線。每個(gè)條目都agents.list可以覆蓋特定字段。網(wǎng)關(guān)在運(yùn)行時(shí)合并這些覆蓋項(xiàng)：代理特定的配置優(yōu)先，其余部分使用默認(rèn)值。
agents: {
defaults: {
workspace: "~/.openclaw/workspace",
model: {
primary: "anthropic/claude-sonnet-4-5",
fallbacks: [
"openai/gpt-5-mini",
"openrouter/google/gemini-3-flash-preview",
],
},
// Alias shortcuts used with the :model slash command
models: {
"anthropic/claude-haiku-4-5": { alias: "haiku" },
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
"anthropic/claude-opus-4-6": { alias: "opus" },
},
maxConcurrent: 4,
// Context pruning: trims old tool results before each LLM call
contextPruning: {
mode: "cache-ttl", // off | cache-ttl
ttl: "45m",
keepLastAssistants: 2,
minPrunableToolChars: 12000,
softTrim: { maxChars: 2500, headChars: 900, tailChars: 900 },
hardClear: { enabled: true, placeholder: "[Old tool result cleared]" },
tools: { deny: ["browser", "canvas"] },
},
// Compaction: summarizes full history when context window fills
compaction: {
mode: "safeguard", // default | safeguard
reserveTokensFloor: 12000,
identifierPolicy: "strict",
memoryFlush: {
enabled: true,
softThresholdTokens: 6000,
prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
systemPrompt: "Session nearing compaction.",
},
},
// Heartbeat
heartbeat: {
every: "30m",
mode: "next-heartbeat",
},
},
list: [
{ id: "main", default: true },
{
id: "work",
workspace: "~/work-agent",
model: { primary: "anthropic/claude-opus-4-6" },
lane: "work-lane",
laneConcurrency: 4,
},
],
}一個(gè)關(guān)鍵限制：某些字段僅在代理級(jí)別生效，如果按代理設(shè)置，agents.defaults則會(huì)被靜默忽略。壓縮設(shè)置、瀏覽器配置文件默認(rèn)值和思考級(jí)別覆蓋都屬于此類。網(wǎng)關(guān)不會(huì)發(fā)出警告——熱重載根本不會(huì)執(zhí)行。此命令會(huì)查找并刪除這些無(wú)效的代理級(jí)別鍵。請(qǐng)務(wù)必在編輯代理特定配置后運(yùn)行此命令。openclaw doctor --fix
上下文剪枝與上下文壓縮：詳解
contextPruning在每次 LLM 調(diào)用之前運(yùn)行。它會(huì)檢查內(nèi)存中的上下文，并修剪超過(guò) TTL 或大小閾值的舊工具結(jié)果。它不會(huì)觸及磁盤(pán)上的會(huì)話文件，只會(huì)處理發(fā)送給模型的內(nèi)容。如果沒(méi)有 contextPruning，運(yùn)行多次工具調(diào)用的會(huì)話會(huì)在上下文中積累巨大的工具結(jié)果有效負(fù)載。這正是 GitHub 問(wèn)題 #2254 中記錄的模式的根本原因：35 條消息生成了一個(gè) 2.9MB 的會(huì)話文件和一個(gè)包含 208,467 個(gè)令牌的上下文，當(dāng)超出模型 200k 的限制時(shí)，上下文會(huì)靜默停止響應(yīng)。啟用 contextPruningcontextPruning可以避免mode: "cache-ttl"這種情況。
當(dāng)上下文窗口接近其極限時(shí)，壓縮操作會(huì)運(yùn)行。網(wǎng)關(guān)會(huì)匯總會(huì)話歷史記錄，并可選擇先通過(guò) `dual memory file` 將備注寫(xiě)入每日內(nèi)存文件memoryFlush，然后用匯總結(jié)果替換完整的歷史記錄。"safeguard"對(duì)于非常長(zhǎng)的歷史記錄，此模式會(huì)進(jìn)行分塊匯總，而不是嘗試在一次 LLM 調(diào)用中匯總所有內(nèi)容。生產(chǎn)環(huán)境中應(yīng)同時(shí)啟用這兩個(gè)功能——較舊的配置可能contextPruning根本沒(méi)有啟用，因?yàn)樗髞?lái)成為了默認(rèn)設(shè)置。
模型部分
models: {
mode: "merge", // merge = combine provider lists; replace = replace defaults
providers: {
anthropic: {
apiKey: "${ANTHROPIC_API_KEY}",
},
openai: {
apiKey: "${OPENAI_API_KEY}",
},
// LM Studio (OpenAI-compatible local server)
"lmstudio": {
baseUrl: "http://127.0.0.1:1234/v1",
apiKey: "lmstudio",
api: "openai-responses",
models: [
{
id: "lmstudio/qwen2.5-coder-7b",
name: "Qwen 2.5 Coder 7B",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32768,
maxTokens: 8000,
},
],
},
// Ollama
ollama: {
baseUrl: "http://localhost:11434",
apiKey: "ollama-local",
api: "openai-completions",
models: [ ... ],
},
},
}該api字段控制使用的請(qǐng)求格式。"openai-responses"適用于大多數(shù)兼容 OpenAI 的本地服務(wù)器；"openai-completions"適用于 Ollama；"anthropic"適用于 Anthropic API。如果模型不支持工具調(diào)用，請(qǐng)進(jìn)行設(shè)置reasoning: false，并且不要將其用作主代理模型——OpenClaw 的工具系統(tǒng)需要函數(shù)調(diào)用支持。
身份驗(yàn)證部分：提供商故障轉(zhuǎn)移配置文件
每個(gè)提供商支持多個(gè)身份驗(yàn)證配置文件，以便在速率限制時(shí)自動(dòng)進(jìn)行故障轉(zhuǎn)移。會(huì)話始終綁定到一個(gè)配置文件（用于緩存預(yù)熱），并在緩存/new壓縮時(shí)重置：
auth: {
profiles: {
"anthropic:subscription": { mode: "oauth", email: "you@example.com" },
"anthropic:api": { mode: "api_key", apiKey: "${ANTHROPIC_API_KEY}" },
"openai:default": { mode: "api_key", apiKey: "${OPENAI_API_KEY}" },
},
order: {
anthropic: ["anthropic:subscription", "anthropic:api"],
openai: ["openai:default"],
},
}當(dāng)某個(gè)模型達(dá)到速率限制或身份驗(yàn)證失敗時(shí)，OpenClaw 會(huì)嘗試使用該提供商列表中的下一個(gè)模型。如果某個(gè)提供商的所有模型都失敗，則會(huì)切換到列表中的下一個(gè)模型agents.defaults.model.fallbacks。配置跨提供商回退機(jī)制（Anthropic → OpenAI，而不是 Anthropic → Anthropic）可以避免已知問(wèn)題，即一個(gè)模型達(dá)到限制會(huì)導(dǎo)致整個(gè)提供商進(jìn)入冷卻狀態(tài)。
會(huì)話部分
session: {
dmScope: "per-channel-peer",
// Options:
// "main" — all DMs share one session (single-user default)
// "per-peer" — isolate by sender ID across all channels
// "per-channel-peer" — isolate by sender + channel (recommended for multi-user)
// "per-account-channel-peer" — most granular
threadBindings: {
enabled: true,
idleHours: 24, // auto-unbind thread after this many idle hours
maxAgeHours: 0, // 0 = no max age
},
reset: {
mode: "daily", // none | daily | idle
atHour: 4, // UTC hour for daily reset
idleMinutes: 120, // for idle mode
},
identityLinks: {
// Link one user's identities across channels
alice: ["telegram:123456", "discord:987654"],
},
}適用dmScope: "per-channel-peer"于多人可以私信您的代理的任何場(chǎng)景。默認(rèn)情況下"main"，所有用戶共享同一個(gè)會(huì)話，這意味著 Alice 的私密對(duì)話內(nèi)容對(duì) Bob 可見(jiàn)。這屬于數(shù)據(jù)泄露，而不僅僅是偏好設(shè)置問(wèn)題。請(qǐng)參閱隱私和合規(guī)性指南。
沙盒部分
sandbox: {
mode: "non-main", // off | all | non-main
scope: "session",
docker: {
image: "openclaw-sandbox:bookworm-slim",
network: "none", // no outbound network from sandbox
readOnlyRoot: true,
cpus: "1",
memoryMb: 512,
},
}"non-main"在隔離的 Docker 容器內(nèi)運(yùn)行子代理和定時(shí)任務(wù)，同時(shí)保持主機(jī)上的主 DM 會(huì)話運(yùn)行。"all"所有操作均在沙箱中進(jìn)行。需要在網(wǎng)關(guān)鏡像中包含 Docker CLI OPENCLAW_INSTALL_DOCKER_CLI=1，并需要 Docker 套接字訪問(wèn)權(quán)限。
熱重載：哪些操作可實(shí)時(shí)執(zhí)行，哪些操作需要重啟
需要重啟網(wǎng)關(guān)的設(shè)置：
- gateway.port（gateway.bind無(wú)法重新綁定活動(dòng)套接字）
- gateway.reload（而且gateway.remote，這是有意為之——這些不會(huì)觸發(fā)重新裝彈）
- 沙箱 Docker 鏡像或網(wǎng)絡(luò)配置
- 插件安裝或移除
無(wú)需重啟即可熱應(yīng)用的設(shè)置：模型和回退更改、代理配置更改、通道策略（dmPolicy、allowFrom）、定時(shí)任務(wù)、心跳間隔、工具配置和大多數(shù)會(huì)話設(shè)置。
CLI 參考
設(shè)置和入職
# Interactive setup wizard openclaw onboard # Setup + install daemon in one step (most common first-run command) openclaw onboard --install-daemon # Re-run specific setup steps openclaw configure # Non-interactive (Docker, CI) openclaw onboard --non-interactive # Reset config only (preserves sessions and credentials) openclaw reset --scope config # Reset config + credentials + sessions (keeps workspace) openclaw reset --scope config+creds+sessions # Full nuclear reset (includes workspace) openclaw reset --scope full
醫(yī)生和診斷
openclaw doctor這是整個(gè)命令行界面中最有用的單個(gè)命令。在任何配置更改后、任何升級(jí)后以及網(wǎng)關(guān)出現(xiàn)異常行為時(shí)，都應(yīng)該運(yùn)行它。
# Basic health check (read-only, safe any time) openclaw doctor # Health check + auto-fix openclaw doctor --fix # Deep scan (more thorough, slower) openclaw doctor --deep --yes # Non-interactive (for scripts) openclaw doctor --non-interactive # Full status dump openclaw status --all --deep # Status as JSON openclaw status --json # Direct gateway health probe (works even if daemon is down) openclaw health --json --verbose # Security audit openclaw security audit openclaw security audit --fix # Check for credential leaks openclaw secrets audit --check
網(wǎng)關(guān)管理
# Run in foreground (debugging) openclaw gateway run # Run on a non-default port openclaw gateway run --port 19000 --bind loopback # Force-kill any process on the port, then start fresh openclaw gateway run --force # Daemon control (requires daemon to be installed) openclaw gateway start openclaw gateway stop openclaw gateway restart openclaw gateway status # Install/manage daemon openclaw daemon install openclaw daemon install --user # user-level systemd service openclaw daemon start | stop | restart | status | logs | uninstall # Open Control UI in browser openclaw dashboard # Remote terminal UI (connect to a remote gateway) openclaw tui --url https://example.com --token YOUR_TOKEN
配置管理
建議優(yōu)先openclaw config使用命令行界面寫(xiě)入，而不是直接編輯文件。命令行寫(xiě)入操作會(huì)經(jīng)過(guò)相同的 JSON5 解析器和模式驗(yàn)證，因此不會(huì)引入未知鍵。
# Get a specific value openclaw config get agents.defaults.model.primary openclaw config get gateway.port # Get everything (pretty-printed) openclaw config get # Set a value openclaw config set agents.defaults.heartbeat.every "2h" openclaw config set agents.defaults.maxConcurrent 8 openclaw config set gateway.bind "loopback" # Unset (remove) a key openclaw config unset tools.web.search.apiKey openclaw config unset agents.defaults.heartbeat
渠道管理
# List channels openclaw channels list # Status check (connection health) openclaw channels status openclaw channels status --probe --all # runs extra connectivity checks # Channel-specific logs openclaw channels logs --channel telegram openclaw channels logs --channel discord --limit 100 # Add a channel (interactive wizard) openclaw channels add --channel telegram openclaw channels add --channel discord # Add non-interactively openclaw channels add --channel telegram \ --account main \ --name "My Bot" \ --token "$TELEGRAM_BOT_TOKEN" # WhatsApp and OAuth login (QR scan / browser flow) openclaw channels login openclaw channels login whatsapp # Approve pairing code from a new DM sender openclaw pairing approve telegram CODE123 # Remove a channel (disables by default) openclaw channels remove --channel telegram openclaw channels remove --channel discord --delete # also removes config entry
日志
# Tail live logs (colorized in TTY) openclaw logs --follow # Output as JSON (one event per line, for piping) openclaw logs --json # Limit output lines openclaw logs --limit 200 # Filter by log level openclaw logs --level warn # Channel-specific logs openclaw channels logs --channel whatsapp
模型管理
# List configured models openclaw models list openclaw models list --all # includes full catalog # Check model status and auth openclaw models status openclaw models status --probe # test connectivity per provider # Change primary model openclaw models set anthropic/claude-sonnet-4-5 # Set image model (for vision inputs) openclaw models set-image openai/gpt-4o # Manage aliases openclaw models aliases list openclaw models aliases add fast anthropic/claude-haiku-4-5 # Manage fallbacks openclaw models fallbacks list openclaw models fallbacks add openai/gpt-5-mini openclaw models fallbacks clear # Auth management openclaw models auth add openclaw models auth setup-token openclaw models auth order get openclaw models auth order set anthropic "anthropic:subscription,anthropic:api"
代理管理
# List agents openclaw agents list # Add an agent (interactive) openclaw agents add # Add non-interactively openclaw agents add --id "work" --workspace ~/work-agent --non-interactive # List routing bindings openclaw agents acp list # Add binding (route a channel/group to a specific agent) openclaw agents acp add --agent work --channel telegram --group-id -1001234567 # Remove binding openclaw agents acp remove --agent work --channel telegram # Run one agent turn directly (bypasses channel) openclaw agent --message "What needs my attention today?" # Delete an agent openclaw agents delete --id work
內(nèi)存管理
# Memory index status openclaw memory status # Re-index all workspace memory files openclaw memory index --all # Search memory openclaw memory search --query "deployment notes" # Send a message to a specific session openclaw message agent --session "session-key" --message "Status update?"
定時(shí)任務(wù)管理
# List all cron jobs openclaw cron list --all # Show cron job status openclaw cron status # Add a cron job (one-time at specific time) openclaw cron add \ --name "morning-brief" \ --at "2026-04-01T09:00:00Z" \ --message "Summarize emails and calendar for today" # Add recurring (interval in milliseconds) openclaw cron add \ --name "hourly-check" \ --every 3600000 \ --message "Check for priority items" # Add with cron expression openclaw cron add \ --name "weekly-report" \ --cron "0 9 * * 1" \ --message "Generate weekly summary" # Run a job immediately (ignoring schedule) openclaw cron run --id morning-brief # Enable/disable openclaw cron enable --id morning-brief openclaw cron disable --id morning-brief # View run history openclaw cron runs --id morning-brief --limit 10 # Edit an existing job openclaw cron edit --id morning-brief # Remove a job openclaw cron rm --id morning-brief
技能和插件
# List installed skills openclaw skills list # Show skill details openclaw skills info web-search # Check eligibility (verify requirements are met) openclaw skills check --eligible # Plugin management openclaw plugins list openclaw plugins info my-plugin openclaw plugins install my-plugin openclaw plugins enable my-plugin openclaw plugins disable my-plugin openclaw plugins doctor # report plugin load errors
會(huì)話和設(shè)備
# List conversation sessions openclaw sessions --json # Clean up old session files openclaw sessions cleanup # Device management openclaw devices list openclaw devices node run --id DEVICE_ID # Approvals (for tools that require human confirmation) openclaw approvals get openclaw approvals set --policy "auto" openclaw approvals allowlist add "exec"
更新管理
# Update to latest stable openclaw update # Switch update channel openclaw update --channel stable # stable | beta | dev # Migrate config after a major version upgrade openclaw migrate
全球標(biāo)志
這些標(biāo)志可以與任何命令一起使用：
--dev # Use dev environment (separate state directory) --profile <name> # Use a named profile (separate state directory) --json # Output as JSON --verbose # Verbose logging --no-color # Disable ANSI color output --log-level debug # Set log level (debug | info | warn | error)
環(huán)境變量
決議令
OpenClaw 會(huì)按以下順序解析環(huán)境變量，先解析的變量?jī)?yōu)先。一旦某個(gè)變量被設(shè)置，后解析的變量就不會(huì)覆蓋它：
- 進(jìn)程環(huán)境（啟動(dòng)網(wǎng)關(guān)時(shí) shell 中已有的變量）
- .env在當(dāng)前工作目錄中（如果網(wǎng)關(guān)啟動(dòng)時(shí)存在）
- ~/.openclaw/.env（全局回退）
- env.vars在 openclaw.json 中（內(nèi)聯(lián)配置變量，非覆蓋）
配置塊env.vars用于設(shè)置默認(rèn)值，這些默認(rèn)值不會(huì)覆蓋環(huán)境中已有的值。請(qǐng)將其用于非敏感的配置值。~/.openclaw/.env憑據(jù)信息請(qǐng)使用或處理環(huán)境變量。
關(guān)鍵環(huán)境變量
# Config paths
OPENCLAW_HOME=~/.openclaw # Base directory
OPENCLAW_CONFIG_PATH=/path/to/openclaw.json # Override config file location
# Logging
OPENCLAW_LOG_LEVEL=debug # debug | info | warn | error
OPENCLAW_LOG_FORMAT=json # for structured log output
# Model API keys (referenced via ${VAR} in config)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
# Gateway
OPENCLAW_GATEWAY_TOKEN=your-token # Overrides gateway.auth.token in config配置中的變量替換
任何字符串值都o(jì)penclaw.json可以引用環(huán)境變量${VAR_NAME}。這會(huì)在 Gateway 啟動(dòng)時(shí)進(jìn)行評(píng)估。要使用字面美元符號(hào)，請(qǐng)對(duì)其進(jìn)行轉(zhuǎn)義：$${NOT_A_VAR}。
models: {
providers: {
anthropic: {
apiKey: "${ANTHROPIC_API_KEY}",
},
},
}
channels: {
telegram: {
botToken: "${TELEGRAM_BOT_TOKEN}",
},
}為了更安全地處理憑據(jù)，請(qǐng)使用 SecretRef 系統(tǒng)，而不是直接使用環(huán)境變量。有關(guān)如何從配置中引用 Docker 密鑰、HashiCorp Vault 和 1Password 的信息，請(qǐng)參閱密鑰管理指南。
Shell 環(huán)境集成
此env.shellEnv.enabled: true設(shè)置會(huì)運(yùn)行您的登錄 shell 并從中導(dǎo)入環(huán)境變量。當(dāng)您在 shell 配置文件中設(shè)置了 API 密鑰（例如 `<shell_config_file>` 和 `<shell_config_file> ~/.bashrc` ~/.zshrc）并希望 OpenClaw 能夠自動(dòng)獲取這些密鑰而無(wú)需在 ` <shell_config_file>` 中重復(fù)設(shè)置時(shí)，此功能非常有用~/.openclaw/.env。如果您的 shell 啟動(dòng)緩慢或占用資源過(guò)多，請(qǐng)?jiān)O(shè)置此設(shè)置env.shellEnv.timeoutMs以限制導(dǎo)入等待的時(shí)間。
在版本控制下管理配置
配置文件~/.openclaw/openclaw.json包含基礎(chǔ)架構(gòu)配置（可以安全地進(jìn)行版本控制）和憑據(jù)（絕對(duì)不能提交）。最簡(jiǎn)單的做法是：使用經(jīng)過(guò)脫敏處理的模板進(jìn)行版本控制，將所有敏感值替換為環(huán)境變量引用，并將實(shí)際憑據(jù)僅保留在~/.openclaw/.env密鑰管理器中。
哪些內(nèi)容需要版本控制，哪些內(nèi)容需要排除在外
.gitignoreOpenClaw 配置倉(cāng)庫(kù)的最小示例：
# Credentials .env *.env credentials/ # Sessions (large, ephemeral, contain private conversation content) sessions/ *.jsonl # Memory files (personal content) workspace/memory/ workspace/MEMORY.md # Cron job state (runtime state, not config) cron/runs/ # Runtime state *.lock tmp/
您可以openclaw.json安全地進(jìn)行版本控制的內(nèi)容包括：使用${VAR}引用代替實(shí)際鍵的結(jié)構(gòu)、工作區(qū)技能文件AGENTS.md（SOUL.md如果它們不包含個(gè)人信息）以及 cron 作業(yè)定義cron/jobs.json。
預(yù)提交憑證掃描
添加truffleHog或gitleaks作為 pre-commit hook，以便在提交配置文件之前捕獲任何意外添加到配置文件中的憑據(jù)?？焖偈謩?dòng)檢查：
# Scan for leaked keys before committing
grep -rE "sk-ant-|sk-or-|sk-[A-Za-z0-9]{40}" ~/.openclaw/openclaw.json
# Should find nothing; all key references should be ${VAR} syntax升級(jí)后配置偏差
每個(gè) OpenClaw 版本都可能添加或重命名配置鍵，并且架構(gòu)在不同版本之間也可能發(fā)生變化。升級(jí)后，務(wù)必運(yùn)行openclaw doctor --fix命令刪除過(guò)時(shí)的鍵并添加任何必需的新字段。未能執(zhí)行此操作是導(dǎo)致設(shè)置看似已配置但未生效的最常見(jiàn)原因——從架構(gòu)中靜默刪除的舊鍵會(huì)被忽略而不是報(bào)錯(cuò)，因此網(wǎng)關(guān)可以啟動(dòng)，但設(shè)置沒(méi)有任何作用。有關(guān)完整的升級(jí)檢查清單，請(qǐng)參閱升級(jí)和維護(hù)指南。
到此這篇關(guān)于OpenClaw CLI 和配置文件參考完整指南的文章就介紹到這了,更多相關(guān)OpenClaw CLI 配置文件內(nèi)容請(qǐng)搜索腳本之家以前的文章或繼續(xù)瀏覽下面的相關(guān)文章，希望大家以后多多支持腳本之家！
相關(guān)文章
OpenClaw常用操作命令完整速查手冊(cè)：從入門(mén)到精通的終端 CLI & 聊天指令全解析
作為 OpenClaw 生態(tài)（包括 PicoClaw、ZeroClaw、losterAI、EasyClaw 等系列開(kāi)源應(yīng)用）的核心用戶，我根據(jù)開(kāi)源資料和個(gè)人使用體驗(yàn)整理了這份全網(wǎng)最全的命令速查手冊(cè)2026-03-09
OpenClaw 使用 JSON/JSON5 格式的配置文件來(lái)管理系統(tǒng)所有組件的設(shè)置，支持靈活的配置覆蓋、環(huán)境變量注入、多配置文件合并、熱重載等功能,本文就來(lái)詳細(xì)的介紹一下OpenClaw主2026-03-10
