first commit
This commit is contained in:
587
content/gateway/configuration-examples.md
Normal file
587
content/gateway/configuration-examples.md
Normal file
@@ -0,0 +1,587 @@
|
||||
---
|
||||
read_when:
|
||||
- 学习如何配置 OpenClaw
|
||||
- 寻找配置示例
|
||||
- 首次设置 OpenClaw
|
||||
summary: 符合模式的常见 OpenClaw 设置配置示例
|
||||
title: 配置示例
|
||||
x-i18n:
|
||||
generated_at: "2026-02-03T07:48:39Z"
|
||||
model: claude-opus-4-5
|
||||
provider: pi
|
||||
source_hash: 00e9286722653f2748137d5bc641d528b160de16a58015ca7674a3a302f4b2c3
|
||||
source_path: gateway/configuration-examples.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 配置示例
|
||||
|
||||
以下示例与当前配置模式一致。有关详尽的参考和每个字段的说明，请参阅[配置](/gateway/configuration)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 绝对最小配置
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: { workspace: "~/.openclaw/workspace" },
|
||||
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
|
||||
}
|
||||
```
|
||||
|
||||
保存到 `~/.openclaw/openclaw.json`，你就可以从该号码私信机器人了。
|
||||
|
||||
### 推荐的入门配置
|
||||
|
||||
```json5
|
||||
{
|
||||
identity: {
|
||||
name: "Clawd",
|
||||
theme: "helpful assistant",
|
||||
emoji: "🦞",
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: { primary: "anthropic/claude-sonnet-4-5" },
|
||||
},
|
||||
channels: {
|
||||
whatsapp: {
|
||||
allowFrom: ["+15555550123"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 扩展示例（主要选项）
|
||||
|
||||
> JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以使用。
|
||||
|
||||
```json5
|
||||
{
|
||||
// 环境 + shell
|
||||
env: {
|
||||
OPENROUTER_API_KEY: "sk-or-...",
|
||||
vars: {
|
||||
GROQ_API_KEY: "gsk-...",
|
||||
},
|
||||
shellEnv: {
|
||||
enabled: true,
|
||||
timeoutMs: 15000,
|
||||
},
|
||||
},
|
||||
|
||||
// 认证配置文件元数据（密钥存储在 auth-profiles.json 中）
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
|
||||
"anthropic:work": { provider: "anthropic", mode: "api_key" },
|
||||
"openai:default": { provider: "openai", mode: "api_key" },
|
||||
"openai-codex:default": { provider: "openai-codex", mode: "oauth" },
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:me@example.com", "anthropic:work"],
|
||||
openai: ["openai:default"],
|
||||
"openai-codex": ["openai-codex:default"],
|
||||
},
|
||||
},
|
||||
|
||||
// 身份
|
||||
identity: {
|
||||
name: "Samantha",
|
||||
theme: "helpful sloth",
|
||||
emoji: "🦥",
|
||||
},
|
||||
|
||||
// 日志
|
||||
logging: {
|
||||
level: "info",
|
||||
file: "/tmp/openclaw/openclaw.log",
|
||||
consoleLevel: "info",
|
||||
consoleStyle: "pretty",
|
||||
redactSensitive: "tools",
|
||||
},
|
||||
|
||||
// 消息格式
|
||||
messages: {
|
||||
messagePrefix: "[openclaw]",
|
||||
responsePrefix: ">",
|
||||
ackReaction: "👀",
|
||||
ackReactionScope: "group-mentions",
|
||||
},
|
||||
|
||||
// 路由 + 队列
|
||||
routing: {
|
||||
groupChat: {
|
||||
mentionPatterns: ["@openclaw", "openclaw"],
|
||||
historyLimit: 50,
|
||||
},
|
||||
queue: {
|
||||
mode: "collect",
|
||||
debounceMs: 1000,
|
||||
cap: 20,
|
||||
drop: "summarize",
|
||||
byChannel: {
|
||||
whatsapp: "collect",
|
||||
telegram: "collect",
|
||||
discord: "collect",
|
||||
slack: "collect",
|
||||
signal: "collect",
|
||||
imessage: "collect",
|
||||
webchat: "collect",
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// 工具
|
||||
tools: {
|
||||
media: {
|
||||
audio: {
|
||||
enabled: true,
|
||||
maxBytes: 20971520,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||||
// 可选的 CLI 回退（Whisper 二进制）：
|
||||
// { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
|
||||
],
|
||||
timeoutSeconds: 120,
|
||||
},
|
||||
video: {
|
||||
enabled: true,
|
||||
maxBytes: 52428800,
|
||||
models: [{ provider: "google", model: "gemini-3-flash-preview" }],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// 会话行为
|
||||
session: {
|
||||
scope: "per-sender",
|
||||
reset: {
|
||||
mode: "daily",
|
||||
atHour: 4,
|
||||
idleMinutes: 60,
|
||||
},
|
||||
resetByChannel: {
|
||||
discord: { mode: "idle", idleMinutes: 10080 },
|
||||
},
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
store: "~/.openclaw/agents/default/sessions/sessions.json",
|
||||
typingIntervalSeconds: 5,
|
||||
sendPolicy: {
|
||||
default: "allow",
|
||||
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
|
||||
},
|
||||
},
|
||||
|
||||
// 渠道
|
||||
channels: {
|
||||
whatsapp: {
|
||||
dmPolicy: "pairing",
|
||||
allowFrom: ["+15555550123"],
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["+15555550123"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "YOUR_TELEGRAM_BOT_TOKEN",
|
||||
allowFrom: ["123456789"],
|
||||
groupPolicy: "allowlist",
|
||||
groupAllowFrom: ["123456789"],
|
||||
groups: { "*": { requireMention: true } },
|
||||
},
|
||||
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_DISCORD_BOT_TOKEN",
|
||||
dm: { enabled: true, allowFrom: ["steipete"] },
|
||||
guilds: {
|
||||
"123456789012345678": {
|
||||
slug: "friends-of-openclaw",
|
||||
requireMention: false,
|
||||
channels: {
|
||||
general: { allow: true },
|
||||
help: { allow: true, requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
slack: {
|
||||
enabled: true,
|
||||
botToken: "xoxb-REPLACE_ME",
|
||||
appToken: "xapp-REPLACE_ME",
|
||||
channels: {
|
||||
"#general": { allow: true, requireMention: true },
|
||||
},
|
||||
dm: { enabled: true, allowFrom: ["U123"] },
|
||||
slashCommand: {
|
||||
enabled: true,
|
||||
name: "openclaw",
|
||||
sessionPrefix: "slack:slash",
|
||||
ephemeral: true,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// 智能体运行时
|
||||
agents: {
|
||||
defaults: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
userTimezone: "America/Chicago",
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["anthropic/claude-opus-4-5", "openai/gpt-5.2"],
|
||||
},
|
||||
imageModel: {
|
||||
primary: "openrouter/anthropic/claude-sonnet-4-5",
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-opus-4-5": { alias: "opus" },
|
||||
"anthropic/claude-sonnet-4-5": { alias: "sonnet" },
|
||||
"openai/gpt-5.2": { alias: "gpt" },
|
||||
},
|
||||
thinkingDefault: "low",
|
||||
verboseDefault: "off",
|
||||
elevatedDefault: "on",
|
||||
blockStreamingDefault: "off",
|
||||
blockStreamingBreak: "text_end",
|
||||
blockStreamingChunk: {
|
||||
minChars: 800,
|
||||
maxChars: 1200,
|
||||
breakPreference: "paragraph",
|
||||
},
|
||||
blockStreamingCoalesce: {
|
||||
idleMs: 1000,
|
||||
},
|
||||
humanDelay: {
|
||||
mode: "natural",
|
||||
},
|
||||
timeoutSeconds: 600,
|
||||
mediaMaxMb: 5,
|
||||
typingIntervalSeconds: 5,
|
||||
maxConcurrent: 3,
|
||||
heartbeat: {
|
||||
every: "30m",
|
||||
model: "anthropic/claude-sonnet-4-5",
|
||||
target: "last",
|
||||
to: "+15555550123",
|
||||
prompt: "HEARTBEAT",
|
||||
ackMaxChars: 300,
|
||||
},
|
||||
memorySearch: {
|
||||
provider: "gemini",
|
||||
model: "gemini-embedding-001",
|
||||
remote: {
|
||||
apiKey: "${GEMINI_API_KEY}",
|
||||
},
|
||||
extraPaths: ["../team-docs", "/srv/shared-notes"],
|
||||
},
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
perSession: true,
|
||||
workspaceRoot: "~/.openclaw/sandboxes",
|
||||
docker: {
|
||||
image: "openclaw-sandbox:bookworm-slim",
|
||||
workdir: "/workspace",
|
||||
readOnlyRoot: true,
|
||||
tmpfs: ["/tmp", "/var/tmp", "/run"],
|
||||
network: "none",
|
||||
user: "1000:1000",
|
||||
},
|
||||
browser: {
|
||||
enabled: false,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
tools: {
|
||||
allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
|
||||
deny: ["browser", "canvas"],
|
||||
exec: {
|
||||
backgroundMs: 10000,
|
||||
timeoutSec: 1800,
|
||||
cleanupMs: 1800000,
|
||||
},
|
||||
elevated: {
|
||||
enabled: true,
|
||||
allowFrom: {
|
||||
whatsapp: ["+15555550123"],
|
||||
telegram: ["123456789"],
|
||||
discord: ["steipete"],
|
||||
slack: ["U123"],
|
||||
signal: ["+15555550123"],
|
||||
imessage: ["user@example.com"],
|
||||
webchat: ["session:demo"],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// 自定义模型提供商
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
"custom-proxy": {
|
||||
baseUrl: "http://localhost:4000/v1",
|
||||
apiKey: "LITELLM_KEY",
|
||||
api: "openai-responses",
|
||||
authHeader: true,
|
||||
headers: { "X-Proxy-Region": "us-west" },
|
||||
models: [
|
||||
{
|
||||
id: "llama-3.1-8b",
|
||||
name: "Llama 3.1 8B",
|
||||
api: "openai-responses",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 128000,
|
||||
maxTokens: 32000,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
// Cron 作业
|
||||
cron: {
|
||||
enabled: true,
|
||||
store: "~/.openclaw/cron/cron.json",
|
||||
maxConcurrentRuns: 2,
|
||||
},
|
||||
|
||||
// Webhooks
|
||||
hooks: {
|
||||
enabled: true,
|
||||
path: "/hooks",
|
||||
token: "shared-secret",
|
||||
presets: ["gmail"],
|
||||
transformsDir: "~/.openclaw/hooks",
|
||||
mappings: [
|
||||
{
|
||||
id: "gmail-hook",
|
||||
match: { path: "gmail" },
|
||||
action: "agent",
|
||||
wakeMode: "now",
|
||||
name: "Gmail",
|
||||
sessionKey: "hook:gmail:{{messages[0].id}}",
|
||||
messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
|
||||
textTemplate: "{{messages[0].snippet}}",
|
||||
deliver: true,
|
||||
channel: "last",
|
||||
to: "+15555550123",
|
||||
thinking: "low",
|
||||
timeoutSeconds: 300,
|
||||
transform: { module: "./transforms/gmail.js", export: "transformGmail" },
|
||||
},
|
||||
],
|
||||
gmail: {
|
||||
account: "openclaw@gmail.com",
|
||||
label: "INBOX",
|
||||
topic: "projects/<project-id>/topics/gog-gmail-watch",
|
||||
subscription: "gog-gmail-watch-push",
|
||||
pushToken: "shared-push-token",
|
||||
hookUrl: "http://127.0.0.1:18789/hooks/gmail",
|
||||
includeBody: true,
|
||||
maxBytes: 20000,
|
||||
renewEveryMinutes: 720,
|
||||
serve: { bind: "127.0.0.1", port: 8788, path: "/" },
|
||||
tailscale: { mode: "funnel", path: "/gmail-pubsub" },
|
||||
},
|
||||
},
|
||||
|
||||
// Gateway 网关 + 网络
|
||||
gateway: {
|
||||
mode: "local",
|
||||
port: 18789,
|
||||
bind: "loopback",
|
||||
controlUi: { enabled: true, basePath: "/openclaw" },
|
||||
auth: {
|
||||
mode: "token",
|
||||
token: "gateway-token",
|
||||
allowTailscale: true,
|
||||
},
|
||||
tailscale: { mode: "serve", resetOnExit: false },
|
||||
remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
|
||||
reload: { mode: "hybrid", debounceMs: 300 },
|
||||
},
|
||||
|
||||
skills: {
|
||||
allowBundled: ["gemini", "peekaboo"],
|
||||
load: {
|
||||
extraDirs: ["~/Projects/agent-scripts/skills"],
|
||||
},
|
||||
install: {
|
||||
preferBrew: true,
|
||||
nodeManager: "npm",
|
||||
},
|
||||
entries: {
|
||||
"nano-banana-pro": {
|
||||
enabled: true,
|
||||
apiKey: "GEMINI_KEY_HERE",
|
||||
env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
|
||||
},
|
||||
peekaboo: { enabled: true },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 常见模式
|
||||
|
||||
### 多平台设置
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: { workspace: "~/.openclaw/workspace" },
|
||||
channels: {
|
||||
whatsapp: { allowFrom: ["+15555550123"] },
|
||||
telegram: {
|
||||
enabled: true,
|
||||
botToken: "YOUR_TOKEN",
|
||||
allowFrom: ["123456789"],
|
||||
},
|
||||
discord: {
|
||||
enabled: true,
|
||||
token: "YOUR_TOKEN",
|
||||
dm: { allowFrom: ["yourname"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### OAuth 带 API 密钥回退
|
||||
|
||||
```json5
|
||||
{
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:subscription": {
|
||||
provider: "anthropic",
|
||||
mode: "oauth",
|
||||
email: "me@example.com",
|
||||
},
|
||||
"anthropic:api": {
|
||||
provider: "anthropic",
|
||||
mode: "api_key",
|
||||
},
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:subscription", "anthropic:api"],
|
||||
},
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-5",
|
||||
fallbacks: ["anthropic/claude-opus-4-5"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### Anthropic 订阅 + API 密钥，MiniMax 回退
|
||||
|
||||
```json5
|
||||
{
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:subscription": {
|
||||
provider: "anthropic",
|
||||
mode: "oauth",
|
||||
email: "user@example.com",
|
||||
},
|
||||
"anthropic:api": {
|
||||
provider: "anthropic",
|
||||
mode: "api_key",
|
||||
},
|
||||
},
|
||||
order: {
|
||||
anthropic: ["anthropic:subscription", "anthropic:api"],
|
||||
},
|
||||
},
|
||||
models: {
|
||||
providers: {
|
||||
minimax: {
|
||||
baseUrl: "https://api.minimax.io/anthropic",
|
||||
api: "anthropic-messages",
|
||||
apiKey: "${MINIMAX_API_KEY}",
|
||||
},
|
||||
},
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: {
|
||||
primary: "anthropic/claude-opus-4-5",
|
||||
fallbacks: ["minimax/MiniMax-M2.1"],
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 工作机器人（受限访问）
|
||||
|
||||
```json5
|
||||
{
|
||||
identity: {
|
||||
name: "WorkBot",
|
||||
theme: "professional assistant",
|
||||
},
|
||||
agent: {
|
||||
workspace: "~/work-openclaw",
|
||||
elevated: { enabled: false },
|
||||
},
|
||||
channels: {
|
||||
slack: {
|
||||
enabled: true,
|
||||
botToken: "xoxb-...",
|
||||
channels: {
|
||||
"#engineering": { allow: true, requireMention: true },
|
||||
"#general": { allow: true, requireMention: true },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 仅本地模型
|
||||
|
||||
```json5
|
||||
{
|
||||
agent: {
|
||||
workspace: "~/.openclaw/workspace",
|
||||
model: { primary: "lmstudio/minimax-m2.1-gs32" },
|
||||
},
|
||||
models: {
|
||||
mode: "merge",
|
||||
providers: {
|
||||
lmstudio: {
|
||||
baseUrl: "http://127.0.0.1:1234/v1",
|
||||
apiKey: "lmstudio",
|
||||
api: "openai-responses",
|
||||
models: [
|
||||
{
|
||||
id: "minimax-m2.1-gs32",
|
||||
name: "MiniMax M2.1 GS32",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
contextWindow: 196608,
|
||||
maxTokens: 8192,
|
||||
},
|
||||
],
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## 提示
|
||||
|
||||
- 如果你设置 `dmPolicy: "open"`，匹配的 `allowFrom` 列表必须包含 `"*"`。
|
||||
- 提供商 ID 各不相同（电话号码、用户 ID、频道 ID）。使用提供商文档确认格式。
|
||||
- 稍后添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
|
||||
- 参阅[提供商](/channels/whatsapp)和[故障排除](/gateway/troubleshooting)了解更深入的设置说明。
|
||||
Reference in New Issue
Block a user