Mikael Hugo 4c98cb8c33 fix: make autonomous mode canonical

2026-05-05 15:42:10 +02:00

16 KiB

Raw Blame History

Provider 设置指南

这是一份覆盖 SF 所有受支持 LLM providers 的分步配置指南。如果你已经运行过 onboarding 向导（sf config）并选择了 provider，很可能已经配置完成，可以在会话中用 /model 检查。

快速参考

Provider	认证方式	环境变量	配置文件
Anthropic	API key	`ANTHROPIC_API_KEY`	—
OpenAI	API key	`OPENAI_API_KEY`	—
Google Gemini	API key	`GEMINI_API_KEY`	—
OpenRouter	API key	`OPENROUTER_API_KEY`	可选 `models.json`
Groq	API key	`GROQ_API_KEY`	—
xAI	API key	`XAI_API_KEY`	—
Mistral	API key	`MISTRAL_API_KEY`	—
GitHub Copilot	OAuth	`GH_TOKEN`	—
Amazon Bedrock	IAM credentials	`AWS_PROFILE` 或 `AWS_ACCESS_KEY_ID`	—
Vertex AI	ADC	`GOOGLE_APPLICATION_CREDENTIALS`	—
Azure OpenAI	API key	`AZURE_OPENAI_API_KEY`	—
Ollama	无（本地）	—	需要 `models.json`
LM Studio	无（本地）	—	需要 `models.json`
vLLM / SGLang	无（本地）	—	需要 `models.json`

内置 Providers

内置 providers 的 models 已经预注册在 SF 里。你只需要提供认证信息。

Anthropic（Claude）

推荐。 Anthropic models 集成最深，支持内置 Web 搜索、extended thinking 和 prompt caching。

选项 A：API key（推荐）

export ANTHROPIC_API_KEY="sk-ant-..."

或者运行 sf config，在提示时粘贴 key。

获取 key： console.anthropic.com/settings/keys

选项 B：Claude Code CLI

如果你有 Claude Pro 或 Max 订阅，可以通过 Anthropic 官方的 Claude Code CLI 完成认证。安装后执行 claude 登录，随后 SF 会自动检测并经由该通道路由：

# 安装 Claude Code CLI（见 https://docs.anthropic.com/en/docs/claude-code）
claude
# 按提示登录，然后启动 SF
sf

SF 会检测你本地的 Claude Code 安装，并把它作为已认证的 Anthropic surface 使用。这是 Anthropic 订阅用户符合 TOS 的方式，SF 不会直接处理你的订阅凭据。

注意： SF 不支持 Anthropic 的浏览器 OAuth 登录。请改用 API key 或 Claude Code CLI。

Runtime 边界： SF 可以把 Claude Code、Codex 或 Gemini CLI core 作为 model/runtime adapter 使用。这些 adapter 不是项目 MCP 依赖，SF 也不会把自己的 workflow 暴露成 MCP server。请直接运行 sf 或 /sf autonomous；MCP 配置只用于 SF 需要调用的外部工具。

OpenAI

export OPENAI_API_KEY="sk-..."

或者运行 sf config，选择 “Paste an API key” 然后选择 “OpenAI”。

获取 key： platform.openai.com/api-keys

Google Gemini

export GEMINI_API_KEY="..."

获取 key： aistudio.google.com/app/apikey

OpenRouter

OpenRouter 通过单个 API key 聚合了多个 providers 的 200+ models。

第 1 步：获取 API key

访问 openrouter.ai/keys 创建一个 key。

第 2 步：设置 key

export OPENROUTER_API_KEY="sk-or-..."

或者运行 sf config，选择 “Paste an API key” 然后选择 “OpenRouter”。

第 3 步：切换到 OpenRouter model

在 SF 会话中输入 /model 并选择一个 OpenRouter model。OpenRouter models 都以 openrouter/ 为前缀（例如 openrouter/anthropic/claude-sonnet-4）。

可选：通过 models.json 添加自定义 OpenRouter models

如果你想使用不在内置列表中的 model，可把它写进 ~/.sf/agent/models.json：

{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "OPENROUTER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "meta-llama/llama-3.3-70b",
          "name": "Llama 3.3 70B (OpenRouter)",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 131072,
          "maxTokens": 32768,
          "cost": { "input": 0.3, "output": 0.3, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

注意：这里的 apiKey 字段写的是环境变量名，不是字面 key。SF 会自动解析它。你也可以改用字面值或 shell 命令（见值解析）。

可选：路由到指定上游 provider

你可以通过 modelOverrides 控制 OpenRouter 实际选用哪个上游 provider：

{
  "providers": {
    "openrouter": {
      "modelOverrides": {
        "anthropic/claude-sonnet-4": {
          "compat": {
            "openRouterRouting": {
              "only": ["amazon-bedrock"]
            }
          }
        }
      }
    }
  }
}

Groq

export GROQ_API_KEY="gsk_..."

获取 key： console.groq.com/keys

xAI（Grok）

export XAI_API_KEY="xai-..."

获取 key： console.x.ai

Mistral

export MISTRAL_API_KEY="..."

获取 key： console.mistral.ai/api-keys

GitHub Copilot

使用 OAuth，通过浏览器登录：

sf config
# 选择 "Sign in with your browser" → "GitHub Copilot"

要求你拥有有效的 GitHub Copilot 订阅。

Amazon Bedrock

Bedrock 使用 AWS IAM 凭据，而不是 API key。下面任意一种都可以：

# 选项 1：命名 profile
export AWS_PROFILE="my-profile"

# 选项 2：IAM keys
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"

# 选项 3：Bedrock API key（bearer token）
export AWS_BEARER_TOKEN_BEDROCK="..."

ECS task roles 和 IRSA（Kubernetes）也会被自动检测。

Vertex AI 上的 Anthropic

使用 Google Cloud Application Default Credentials：

gcloud auth application-default login
export ANTHROPIC_VERTEX_PROJECT_ID="my-project-id"

或者设置 GOOGLE_CLOUD_PROJECT，并确保 ADC 凭据存在于 ~/.config/gcloud/application_default_credentials.json。

Azure OpenAI

export AZURE_OPENAI_API_KEY="..."

本地 Providers

本地 providers 运行在你的机器上。因为 SF 需要知道 endpoint URL 和可用 models，所以它们都要求配置 models.json。

配置文件位置： ~/.sf/agent/models.json

每次打开 /model 时，这个文件都会自动重新加载，无需重启。

Ollama

第 1 步：安装并启动 Ollama

# macOS
brew install ollama
ollama serve

# 或前往 https://ollama.com 下载

第 2 步：拉取一个 model

ollama pull llama3.1:8b
ollama pull qwen2.5-coder:7b

第 3 步：创建 ~/.sf/agent/models.json

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

apiKey 是 schema 的必填字段，但 Ollama 会忽略它，因此任意值都可以。

第 4 步：选择 model

在 SF 里输入 /model，然后选择你的 Ollama model。

Ollama 提示：

Ollama 不支持 developer role，也不支持 reasoning_effort，因此请始终设置 compat.supportsDeveloperRole: false 和 compat.supportsReasoningEffort: false
如果得到空响应，先检查 ollama serve 是否正在运行，以及 model 是否已经 pull 下来
如果未显式指定，contextWindow 和 maxTokens 默认分别为 128K / 16K。若模型能力不同，请手动覆盖

LM Studio

第 1 步：安装 LM Studio

访问 lmstudio.ai 下载。

第 2 步：启动本地 server

在 LM Studio 中进入 “Local Server” 标签页，加载一个 model，然后点击 “Start Server”。默认端口为 1234。

第 3 步：创建 ~/.sf/agent/models.json

{
  "providers": {
    "lm-studio": {
      "baseUrl": "http://localhost:1234/v1",
      "api": "openai-completions",
      "apiKey": "lm-studio",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "your-model-name",
          "name": "My Local Model",
          "contextWindow": 32768,
          "maxTokens": 4096
        }
      ]
    }
  }
}

把 your-model-name 替换成 LM Studio server 标签页中显示的 model 标识符。

LM Studio 提示：

models.json 里的 model id 必须与 LM Studio server API 返回的值完全一致
LM Studio 默认端口是 1234；如果你改了端口，也要同步修改 baseUrl
如果模型支持更大的上下文，记得上调 contextWindow 和 maxTokens

vLLM

{
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "api": "openai-completions",
      "apiKey": "vllm",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsUsageInStreaming": false
      },
      "models": [
        {
          "id": "meta-llama/Llama-3.1-8B-Instruct",
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

model id 必须与 vllm serve 启动时传入的 --model 参数完全一致。

SGLang

{
  "providers": {
    "sglang": {
      "baseUrl": "http://localhost:30000/v1",
      "api": "openai-completions",
      "apiKey": "sglang",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "meta-llama/Llama-3.1-8B-Instruct"
        }
      ]
    }
  }
}

自定义 OpenAI-Compatible Endpoints

任何实现了 OpenAI Chat Completions API 的 server 都可以和 SF 配合使用。这包括代理（LiteLLM、Portkey、Helicone）、自托管推理服务，以及新出现的 providers。

最快路径：使用 onboarding 向导

sf config
# 选择 "Paste an API key" → "Custom (OpenAI-compatible)"
# 输入：base URL、API key、model ID

这会自动帮你写好 ~/.sf/agent/models.json。

手动配置：

{
  "providers": {
    "my-provider": {
      "baseUrl": "https://my-endpoint.example.com/v1",
      "apiKey": "MY_PROVIDER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "model-id-here",
          "name": "Friendly Model Name",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

添加自定义 headers（常见于代理）

{
  "providers": {
    "litellm-proxy": {
      "baseUrl": "https://litellm.example.com/v1",
      "apiKey": "MY_API_KEY",
      "api": "openai-completions",
      "headers": {
        "x-custom-header": "value"
      },
      "models": [...]
    }
  }
}

支持 thinking mode 的 Qwen models

对于 Qwen-compatible servers，可用 thinkingFormat 打开 thinking mode：

{
  "compat": {
    "thinkingFormat": "qwen",
    "supportsDeveloperRole": false
  }
}

如果该 server 要求 chat_template_kwargs.enable_thinking，请改用 "qwen-chat-template"。

关于 compat 字段、modelOverrides、值解析和高级配置的完整说明，见自定义模型。

常见坑点

使用有效 key 仍提示 “Authentication failed”

原因： key 虽然设在 shell 中，但 SF 看不到。

解决： 确认你是在同一个终端里 export 了该环境变量并运行 sf。或者直接用 sf config 把 key 保存进 ~/.sf/agent/auth.json，这样就能跨会话持久化。

OpenRouter models 没出现在 `/model`

原因： 没有设置 OPENROUTER_API_KEY，因此 SF 会隐藏 OpenRouter models。

解决： 设置 key 并重启 SF：

export OPENROUTER_API_KEY="sk-or-..."
sf

Ollama 返回空响应

原因： Ollama server 没有运行，或者对应 model 尚未 pull。

解决：

# 确认 server 正在运行
curl http://localhost:11434/v1/models

# 如果 model 缺失则先 pull
ollama pull llama3.1:8b

LM Studio model ID 不匹配

原因： models.json 中的 id 和 LM Studio 实际通过 API 暴露的值不一致。

解决： 去 LM Studio 的 server 标签页查看精确的 model 标识符。它通常会包含文件名或量化后缀（例如 lmstudio-community/Meta-Llama-3.1-8B-Instruct-GGUF）。

本地 models 报 `developer` role 错误

原因： 大多数本地推理 server 不支持 OpenAI 的 developer message role。

解决： 在 provider 配置里添加 compat.supportsDeveloperRole: false。这样 SF 会改用 system message：

{
  "compat": {
    "supportsDeveloperRole": false,
    "supportsReasoningEffort": false
  }
}

本地 models 报 `stream_options` 错误

原因： 部分 server 不支持 stream_options: { include_usage: true }。

解决： 添加 compat.supportsUsageInStreaming: false：

{
  "compat": {
    "supportsUsageInStreaming": false
  }
}

报 “apiKey is required” 校验错误

原因： models.json schema 规定：只要定义了 models，就必须存在 apiKey。

解决： 对于不需要认证的本地 server，填一个占位值即可：

"apiKey": "not-needed"

自定义 models 的成本显示为 `$0.00`

这是预期行为。SF 对自定义 models 的默认成本就是 0。如果你想获得准确的成本跟踪，需要自己填写 cost 字段：

"cost": { "input": 0.15, "output": 0.60, "cacheRead": 0.015, "cacheWrite": 0.19 }

这些值的单位都是每百万 tokens。

验证你的配置

完成 provider 配置后：

启动 SF：
```
sf
```
检查可用 models：
```
/model
```
列表里应该能看到该 provider 的 models。
切换到对应 model： 在 /model 选择器中选中它。
发送一条测试消息： 输入任意内容，确认 model 可以正常响应。

如果 model 没有出现，请检查：

当前 shell 中是否设置了对应环境变量
models.json 是否是合法 JSON（可执行 cat ~/.sf/agent/models.json | python3 -m json.tool）
本地 providers 的 server 是否已经运行

如果还需要更多帮助，请查看故障排查，或者在会话中运行 /sf doctor。

16 KiB Raw Blame History Unescape Escape