Fal

OpenClaw 随附了一个内置的 fal 提供方，用于托管式图像、视频和音乐生成。

入门指南¶

1. 获取 API 密钥

在 fal.ai/dashboard/keys 创建一个密钥。

2. 设置 API 密钥

openclaw onboard --auth-choice fal-api-key

非交互式安装可以传入 --fal-api-key <key>，或导出 FAL_KEY 环境变量。Onboarding 流程还会在未配置任何图像模型时，将 fal/fal-ai/flux/dev 设置为默认图像模型。

3. 设置默认图像模型

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/fal-ai/flux/dev",
        },
      },
    },
  },
}

图像生成¶

内置的 fal 图像生成提供方默认使用 fal/fal-ai/flux/dev。

编辑请求（通过共享的 image / images 参数传递参考图像）会路由到各模型对应的编辑端点，并带有各模型的参考图像数量限制：

GPT Image 2.5¶

选择以下任一变体：

• fal/openai/gpt-image-2.5/flare/text-to-image
• fal/openai/gpt-image-2.5/sunburst/text-to-image

提供参考图像时会选择同级 /edit 端点。你也可以显式选择 fal/openai/gpt-image-2.5/flare/edit 或 fal/openai/gpt-image-2.5/sunburst/edit。

两个变体都支持 quality: "low"、"medium"、"high"、"xhigh"、"max" 或 "auto"。fal 的默认值为 high。它们接受 background: "transparent"、"opaque" 或 "auto"。如需透明背景，请使用 outputFormat: "png" 或 "webp"。这些控制项对旧版 fal 模型不生效。

使用 size: "auto" 或显式尺寸，例如 1536x864。尺寸必须能被 16 整除，且任何一边不得超过 3840 像素。总像素数必须在 655,360 到 8,294,400 之间，宽高比在 1:3 到 3:1 之间。OpenClaw 会将宽高比提示转换为有效尺寸。例如，aspectRatio: "3:2" 会生成 1536x1024。使用 size 可选择精确尺寸。OpenClaw 会拒绝无效的显式尺寸。这些模型拒绝 resolution 覆盖。没有几何提示的编辑请求会沿用 fal 的自动尺寸选择。

openclaw infer image generate \
  --model fal/openai/gpt-image-2.5/flare/text-to-image \
  --prompt "A simple red circle sticker" \
  --quality low --size 1024x1024 --json

openclaw infer image edit \
  --model fal/openai/gpt-image-2.5/sunburst/edit \
  --file /path/to/reference.png \
  --prompt "Keep the shape and change the color to blue" \
  --quality low --size auto --json

Krea 2¶

Krea 2 模型使用 fal 原生的 Krea 负载结构。OpenClaw 发送 aspect_ratio、creativity 和 image_style_references，而不是 Flux 使用的通用 image_size / 编辑端点负载。模型引用为：

• fal/krea/v2/medium/text-to-image
• fal/krea/v2/large/text-to-image

使用 Medium 可获得更快的表现力插画、动漫、绘画和艺术风格。使用 Large 则速度较慢，但可获得照片级逼真、原始纹理、胶片颗粒和精致外观。Krea 默认使用 fal.creativity: "medium"；支持的值有 raw、low、medium 和 high。

Krea 2 在 fal 的请求模式中公开的是宽高比，而不是 image_size。优先使用 aspectRatio；OpenClaw 会将 size 映射到最接近的受支持 Krea 宽高比，并且对于 Krea 会拒绝 resolution，而不是直接丢弃它。

当你希望从公开 output_format 的 fal 模型获得 PNG 输出时，请使用 outputFormat: "png"。除 GPT Image 2.5 外，fal 模型在 OpenClaw 中未声明透明背景控制。它们会将 background 报告为被忽略的覆盖项。 Krea 2 端点未通过 fal 公开 output_format 请求字段，因此 OpenClaw 会拒绝 Krea 请求中的 outputFormat 覆盖项。

要使用 Krea 2 Medium：

{
  agents: {
    defaults: {
      mediaModels: {
        image: {
          primary: "fal/krea/v2/medium/text-to-image",
        },
      },
    },
  },
}

视频生成¶

内置的 fal 视频生成提供商默认为 fal/fal-ai/minimax/video-01-live。

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/bytedance/seedance-2.0/fast/reference-to-video",
        },
      },
    },
  },
}

{
  agents: {
    defaults: {
      mediaModels: {
        video: {
          primary: "fal/fal-ai/heygen/v2/video-agent",
        },
      },
    },
  },
}

音乐生成¶

内置的 fal 插件还为共享的 music_generate 工具注册了音乐生成提供商。

将 fal 用作默认音乐提供商：

{
  agents: {
    defaults: {
      mediaModels: {
        music: {
          primary: "fal/fal-ai/minimax-music/v2.6",
        },
      },
    },
  },
}

fal-ai/minimax-music/v2.6 支持显式歌词和纯音乐模式，但不能在同一请求中同时使用。ACE-Step 和 Stable Audio 是 提示词转音频端点；当你希望使用这些模型系列时，可通过 model 覆盖项选择它们。ACE-Step 拒绝显式歌词；Stable Audio 拒绝 歌词和纯音乐模式。

相关¶

图像生成

共享图像工具参数和提供商选择。

视频生成

共享视频工具参数和提供商选择。

音乐生成

共享音乐工具参数和提供商选择。

配置参考

代理默认设置，包括图像、视频和音乐模型选择。