mirror of
https://github.com/openclaw/openclaw.git
synced 2026-03-17 04:50:51 +00:00
a3ec2d0734
What: - update zh-CN glossary, TM, and translator prompt - regenerate zh-CN docs and apply targeted fixes - add zh-CN AGENTS pipeline guidance Why: - address terminology/spacing feedback from #6995 Tests: - pnpm build && pnpm check && pnpm test
588 lines
14 KiB
Markdown
588 lines
14 KiB
Markdown
---
|
||
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)了解更深入的设置说明。
|