高级配置

本文介绍 Wesclaw 的高级配置选项，包括配置文件详解、环境变量、代理设置、日志管理和性能调优。

config.yaml 详解

Wesclaw 桌面版使用 YAML 格式的配置文件。首次运行 wesclaw init 时自动创建。

配置文件位置

操作系统	路径
macOS	`~/Library/Application Support/wesclaw/config.yaml`
Linux	`~/.config/wesclaw/config.yaml`
Windows	`%APPDATA%\wesclaw\config.yaml`

可通过环境变量 WESCLAW_CONFIG 自定义路径。

完整配置示例

# Wesclaw 配置文件

# 模型提供商配置
providers:
  - name: my-openai
    type: openai
    base_url: https://api.openai.com/v1
    api_key_ref:
      source: inline
      value: sk-xxxx          # 存储时会自动加密
    models:
      - name: gpt-4o
        context_window: 128000
        supports_vision: true
      - name: gpt-4o-mini
        context_window: 128000

  - name: my-claude
    type: anthropic
    api_key_ref:
      source: env
      value: ANTHROPIC_API_KEY  # 从环境变量读取
    models:
      - name: claude-sonnet-4-20250514
        context_window: 200000
        supports_vision: true

# 默认 Provider 策略
provider_strategy: own_only    # own_only | shared_only | own_first | shared_first

# 治理配置
governance:
  mode: open                   # open（默认）| locked
  deny_paths:                  # 禁止 AI 访问的路径
    - /etc/passwd
    - ~/.ssh/

# 通用设置
locale: zh-CN
timezone: Asia/Shanghai

# IM 渠道配置
channels:
  - type: wecom
    corp_id: wxXXXXXX
    agent_id: 1000001
    secret_ref:
      source: env
      value: WECOM_SECRET

# 邮件配置
email:
  - address: ai@example.com
    smtp_host: smtp.example.com
    smtp_port: 465
    imap_host: imap.example.com
    imap_port: 993
    password_ref:
      source: env
      value: EMAIL_PASSWORD

# MCP 服务器
mcps:
  - name: local-tools
    transport: stdio
    command: ["/usr/local/bin/my-mcp-server"]

配置分层

配置按以下优先级生效（高 → 低）：

运行时命令（如 /model 命令）
环境变量
config.yaml 文件
内置默认值

环境变量

基础环境变量

变量名	说明	默认值
`WESCLAW_DATA_DIR`	数据存储目录	系统 XDG 目录
`WESCLAW_CONFIG`	配置文件路径	`<config_dir>/config.yaml`
`WESCLAW_LOG_LEVEL`	日志级别	`info`

模型密钥环境变量

API Key 推荐通过环境变量配置，而非写在配置文件中：

# 在 shell 配置文件中添加（如 .zshrc / .bashrc）
export OPENAI_API_KEY="sk-xxxx"
export ANTHROPIC_API_KEY="sk-ant-xxxx"
export AZURE_OPENAI_API_KEY="xxxx"

然后在 config.yaml 中引用：

providers:
  - name: openai
    api_key_ref:
      source: env
      value: OPENAI_API_KEY

SaaS 版环境变量

云端版部署时的额外配置：

变量名	说明
`WESCLAW_SAAS_DATA_DIR`	SaaS 数据目录
`WEISYN_BASE_URL`	平台 API 地址
`JWT_PUBLIC_KEY_PATH`	JWT 公钥路径

代理设置

HTTP 代理

如果需要通过代理访问 AI 模型 API：

# 系统级代理
export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

模型 API 代理

也可以通过修改 base_url 使用代理或中转服务：

providers:
  - name: openai-proxy
    type: openai
    base_url: https://my-proxy.example.com/v1    # 代理地址
    api_key_ref:
      source: env
      value: OPENAI_API_KEY

日志配置

日志文件位置

<数据目录>/logs/
├── wesclaw.log          # 主日志（Go 后端）
└── wesclaw-stderr.log   # 错误日志（崩溃堆栈）

日志级别

通过环境变量控制：

export WESCLAW_LOG_LEVEL=debug    # debug | info | warn | error

查看日志

# macOS
tail -f ~/Library/Application\ Support/wesclaw/logs/wesclaw.log

# 查看错误日志
cat ~/Library/Application\ Support/wesclaw/logs/wesclaw-stderr.log

Electron 前端日志

桌面版 Electron 前端日志位于：

<数据目录>/logs/<timestamp>/

包含 renderer 进程和 main 进程的日志。

性能调优

上下文压缩

对于长对话，引擎会自动压缩上下文以保持性能。你可以关注以下指标：

Token 用量：通过「设置 → 用量统计」查看
对话长度：过长的对话建议开新会话

模型选择

不同场景选择合适的模型可以显著影响性能：

场景	推荐模型	原因
简单问答	GPT-4o-mini / Claude Haiku	快速响应，低成本
复杂分析	GPT-4o / Claude Sonnet	平衡质量与速度
深度推理	Claude Opus / o3	最佳质量

网络优化

使用距离最近的 API 端点
考虑使用带 CDN 加速的代理服务
检查 DNS 解析是否正常

内存管理

Wesclaw 桌面版是 Electron 应用，内存使用建议：

定期重启应用以释放内存
关闭不需要的对话标签页
知识库文件过大时，考虑拆分

配置文件版本

配置文件有内部版本号，升级 Wesclaw 时会自动迁移配置格式。如遇问题：

备份当前配置文件
删除配置文件
运行 wesclaw init 重新生成
手动迁移自定义配置

常见问题

配置不生效

确认 YAML 语法正确（注意缩进）
重启 Wesclaw 使配置生效
检查是否有同名环境变量覆盖了配置

API Key 无法连接

检查网络连接和代理设置
确认 API Key 未过期
使用「设置 → AI 模型 → 测试连接」验证
查看日志中的详细错误信息

配置文件损坏

# 备份当前配置
mv config.yaml config.yaml.bak

# 重新初始化
wesclaw init

# 手动迁移需要的配置项

注意事项

不要在配置文件中存储明文密码：使用 source: env 引用环境变量
修改配置后需重启：大部分配置变更需要重启 Wesclaw 才能生效
YAML 格式敏感：注意缩进使用空格而非 Tab
密钥加密：source: inline 的密钥在存储时会自动加密，但建议仍优先使用环境变量