Gateway 工具与自定义 Provider 配置

tools.* 配置键及自定义 Provider / base URL 设置。

工具配置

工具 Profile

tools.profile 设置基础白名单：

Profile	包含内容
`minimal`	仅 `session_status`
`coding`	`group:fs`、`group:runtime`、`group:web`、`group:sessions`、`group:memory`、`cron`、`image` 等
`messaging`	`group:messaging`、sessions 相关工具
`full`	无限制（同未设置）

本地 onboarding 默认新配置使用 tools.profile: "coding"。

工具分组

分组	工具
`group:runtime`	`exec`, `process`, `code_execution`
`group:fs`	`read`, `write`, `edit`, `apply_patch`
`group:sessions`	`sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn` 等
`group:memory`	`memory_search`, `memory_get`
`group:web`	`web_search`, `x_search`, `web_fetch`
`group:ui`	`browser`, `canvas`
`group:automation`	`heartbeat_respond`, `cron`, `gateway`
`group:messaging`	`message`
`group:media`	`image`, `image_generate`, `music_generate`, `video_generate`, `tts`

tools.allow / tools.deny

全局工具允许/拒绝策略（deny 优先），大小写不敏感，支持 * 通配符：

{
  tools: { deny: ["browser", "canvas"] },
}

注意：deny: ["write"] 不会拒绝 apply_patch，要阻止所有文件修改需明确列出：

{
  tools: { deny: ["write", "edit", "apply_patch"] },
}

tools.byProvider

按 Provider 或模型进一步限制工具：

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.4": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.toolsBySender

按发送者身份限制工具（纵深防御，发送者值来自 channel 适配器）：

{
  tools: {
    toolsBySender: {
      "channel:discord:1234567890123": { alsoAllow: ["group:fs"] },
      "id:guest-user-id": { deny: ["group:runtime", "group:fs"] },
      "*": { deny: ["exec", "process", "write", "edit", "apply_patch"] },
    },
  },
}

键前缀：channel:<channelId>:<senderId>、id:<senderId>、e164:<phone>、username:<handle>、name:<displayName>、"*"

tools.elevated（提升权限）

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123"],
      },
    },
  },
}

提升的 exec 绕过沙箱
/elevated on|off|ask|full 按 session 存储状态

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
    },
  },
}

tools.loopDetection（工具循环检测）

默认禁用，需显式开启：

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

注意：warningThreshold < criticalThreshold < globalCircuitBreakerThreshold，否则校验失败。

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key",  // 或 BRAVE_API_KEY 环境变量
        maxResults: 5,
        timeoutSeconds: 30,
      },
      fetch: {
        enabled: true,
        provider: "firecrawl",  // 可选，省略则自动检测
        maxChars: 50000,
        timeoutSeconds: 30,
        readability: true,
      },
    },
  },
}

tools.media（媒体理解）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      image: { enabled: true, timeoutSeconds: 180 },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

tools.sessions（Session 可见性）

{
  tools: {
    sessions: {
      visibility: "tree",  // self | tree | agent | all
    },
  },
}

self：仅当前 session
tree：当前 session + 其派生的子 agent session（默认）
agent：当前 agent 的所有 session
all：任意 session

自定义 Provider 与 Base URL

{
  models: {
    mode: "merge",  // merge（默认）| replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions",  // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

Provider 字段说明

api：请求适配器，自托管 /v1/chat/completions 后端使用 openai-completions
apiKey：优先使用 SecretRef 或环境变量替换
authHeader: true：强制通过 Authorization Header 传递凭证
headers：代理/租户路由的额外静态 Header
request.proxy：HTTP 代理覆盖（env-proxy 或 explicit-proxy）
request.tls：TLS 覆盖（ca、cert、key、serverName）
request.allowPrivateNetwork：允许 HTTPS 到私网 baseUrl（默认 false）

Provider 示例

LM Studio（本地模型）：

{
  models: {
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
      },
    },
  },
}

MiniMax（Anthropic 兼容）：

{
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
      },
    },
  },
}

Moonshot AI（Kimi）：

{
  models: {
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.6",
            input: ["text", "image"],
            contextWindow: 262144,
            maxTokens: 262144,
          },
        ],
      },
    },
  },
}

模型条目字段

input：输入模态，["text"] 纯文本，["text", "image"] 支持视觉
contextWindow：原生上下文窗口元数据
contextTokens：可选运行时上下文上限（小于 contextWindow 时限制有效上下文）
compat.requiresStringContent：true 时将纯文本 content 数组展平为字符串
compat.thinkingFormat："qwen" 或 "qwen-chat-template"（Qwen 系列思考控制）

Subagents 配置

{
  agents: {
    defaults: {
      subagents: {
        allowAgents: ["research"],
        model: "minimax/MiniMax-M2.7",
        maxConcurrent: 8,
        runTimeoutSeconds: 900,
      },
    },
  },
}

Wiki AI

目录