AI 实战文档

Appearance

配置与目录结构（按官方 Gateway 配置体系） ​

配置入口 ​

  • 初始化/向导：openclaw onboard、openclaw configure
  • 配置查询与修改：openclaw config
  • 网关状态与深度检查：openclaw gateway status --deep

参考：

目录结构 ​

txt
~/.openclaw/
├── config.yaml           # 主配置文件
├── secrets.yaml          # 密钥存储（不提交版本控制）
├── state/                # 运行时状态
│   ├── sessions/         # 会话数据
│   ├── logs/             # 日志文件
│   └── cache/            # 缓存数据
├── skills/               # 自定义 Skills
│   └── my-skill/
│       └── SKILL.md
├── plugins/              # 插件目录
└── logs/                 # 历史日志
    ├── gateway.log
    └── audit.log

你需要重点掌握的配置域 ​

1. gateway.* - 网关配置 ​

yaml
gateway:
  # 网络配置
  host: 127.0.0.1
  port: 18789

  # 认证配置
  auth:
    enabled: true
    type: token # token | password
    token: ${OPENCLAW_GATEWAY_TOKEN}

  # TLS 配置
  tls:
    enabled: false
    cert: /path/to/cert.pem
    key: /path/to/key.pem

  # 重载模式
  reload:
    mode: hybrid # auto | manual | hybrid

  # 速率限制
  rate_limit:
    enabled: true
    requests_per_minute: 60
    burst: 10

2. tools.* - 工具配置 ​

yaml
tools:
  # 基础 profile
  profile: safe # minimal | safe | coding | messaging | full

  # 允许/拒绝列表
  allow:
    - read:*
    - search:*
    - web:fetch
  deny:
    - exec:elevated
    - write:sensitive

  # 按模型提供商限制
  byProvider:
    openai:
      allow: ['*']
    anthropic:
      deny:
        - browser:*

  # 审批策略
  approvals:
    exec:
      mode: ask # off | on-miss | always
      timeout: 300

3. agents.* - Agent 配置 ​

yaml
agents:
  # 默认配置
  defaults:
    model: gpt-4-turbo
    temperature: 0.7
    max_tokens: 4096
    memory:
      enabled: true
      type: conversation
      max_messages: 50

  # 多 Agent 路由
  routing:
    - name: dev-agent
      trigger: 'dev:'
      model: claude-3-opus
      tools: coding
      system_prompt: You are a senior developer...

    - name: pm-agent
      trigger: 'pm:'
      model: gpt-4-turbo
      tools: minimal
      system_prompt: You are a product manager...

4. channels.* - 渠道配置 ​

yaml
channels:
  # Discord 配置
  discord:
    enabled: true
    bot_token: ${secrets.discord_bot_token}
    application_id: ${secrets.discord_app_id}

  # Telegram 配置
  telegram:
    enabled: true
    bot_token: ${secrets.telegram_bot_token}

  # Slack 配置
  slack:
    enabled: true
    app_token: ${secrets.slack_app_token}
    bot_token: ${secrets.slack_bot_token}

5. providers.* - 模型提供商配置 ​

yaml
providers:
  openai:
    api_key: ${secrets.openai_api_key}
    models:
      gpt-4-turbo:
        enabled: true
        cost_limit: 100 # 美元/月
      gpt-3.5-turbo:
        enabled: true
        cost_limit: 50

  anthropic:
    api_key: ${secrets.anthropic_api_key}
    models:
      claude-3-opus:
        enabled: true
        cost_limit: 200

6. secrets.* - 密钥管理 ​

yaml
# secrets.yaml（不提交版本控制）
secrets:
  openai_api_key: sk-xxx
  anthropic_api_key: sk-ant-xxx
  discord_bot_token: xxx
  telegram_bot_token: xxx
  slack_app_token: xoxp-xxx
  slack_bot_token: xoxb-xxx

配置变更优先顺序 ​

  1. 本地最小配置先跑通
  2. 加入渠道与路由规则
  3. 加入工具白名单与审批策略
  4. 最后开放远程接入

常用配置命令 ​

bash
# 查看所有配置
openclaw config list

# 查看特定配置项
openclaw config get gateway.port
openclaw config get tools.profile

# 设置配置项
openclaw config set gateway.port 18800
openclaw config set tools.profile coding

# 导出配置
openclaw config export --output config-backup.yaml

# 导入配置
openclaw config import --input config-backup.yaml

# 验证配置
openclaw config validate

# 重载配置（不重启）
openclaw config reload

配置变更的团队流程 ​

变更前检查 ​

bash
# 1. 备份当前配置
openclaw config export --output config-backup-$(date +%Y%m%d).yaml

# 2. 验证新配置
openclaw config validate --file new-config.yaml

# 3. 预览变更
openclaw config diff --file new-config.yaml

变更后验证 ​

bash
# 1. 检查服务状态
openclaw gateway status --deep

# 2. 检查渠道状态
openclaw channels status --probe

# 3. 检查安全配置
openclaw security audit

# 4. 系统诊断
openclaw doctor

职责分工 ​

  • 开发者：配置语义正确性和可运行性
  • 产品经理：变更影响范围与发布窗口
  • 运维：回滚点与日志监控

配置最佳实践 ​

1. 分环境配置 ​

txt
# config.dev.yaml
gateway:
  auth:
    enabled: false  # 开发环境可选禁用

# config.prod.yaml
gateway:
  auth:
    enabled: true
    type: token

2. 敏感信息隔离 ​

yaml
# config.yaml（可提交版本控制）
providers:
  openai:
    api_key: ${secrets.openai_api_key}

# secrets.yaml（不提交版本控制）
secrets:
  openai_api_key: sk-xxx

3. 配置版本控制 ​

bash
# .gitignore
secrets.yaml
*.local.yaml
state/
logs/

# 追踪配置变更
git add config.yaml
git commit -m "chore: update tools profile"

常见误区 ​

误区 1：误把 sessionKey 当作权限边界 ​

yaml
# ❌ 错误理解：sessionKey 是权限控制
# sessionKey 只是会话标识

# ✅ 正确做法：通过 tools.profile 控制权限
tools:
  profile: safe

误区 2：未配置网关鉴权就开放公网 ​

txt
# ❌ 危险：未启用认证
gateway:
  host: 0.0.0.0  # 暴露公网
  auth:
    enabled: false

# ✅ 正确：启用认证
gateway:
  host: 127.0.0.1  # 本地绑定
  auth:
    enabled: true
    type: token

误区 3：工具权限一次性放开 ​

txt
# ❌ 危险：直接使用 full profile
tools:
  profile: full

# ✅ 正确：渐进式放权
tools:
  profile: safe
  allow:
    - read:*
    - search:*
  approvals:
    exec:
      mode: ask