为Raycast AI打造专属模型代理网关：绕过订阅，自由调用GPT-4o/Claude/Gemini

1. 项目概述：为Raycast AI打造专属的模型代理网关

如果你和我一样，是Raycast的深度用户，同时又对官方AI功能每月10美元的订阅费感到犹豫，或者希望能在Raycast里用上Claude、Gemini等更多非OpenAI的模型，那么这个项目绝对值得你花时间研究一下。raycast-ai-openrouter-proxy本质上是一个“翻译官”，它架设在你的本地电脑上，把Raycast AI发出的请求，从它原本理解的“Ollama协议”，翻译成各种主流AI服务商（如OpenAI、Google、Anthropic、OpenRouter等）都能听懂的“OpenAI兼容API协议”。

这样一来，你就能在Raycast原生的AI聊天、AI命令、快速AI和预设功能里，无缝使用你自己API密钥授权的任何模型。最核心的价值在于，它绕开了Raycast Pro订阅的限制，实现了真正的“自带密钥”（BYOK），让你对自己的数据流向和模型选择拥有完全的控制权。我实测下来，从配置到能用上GPT-4o、Claude 3.5 Sonnet，整个过程不到10分钟，体验非常流畅。

2. 核心原理与架构拆解：它如何成为Raycast与AI模型之间的桥梁？

要理解这个代理的价值，我们得先看看Raycast AI原本的工作方式。Raycast内置的AI功能，其设计初衷是与OpenAI的API直接对话，或者通过其Pro订阅服务来中转。对于想使用本地模型（如通过Ollama部署）的用户，Raycast也预留了一个“Ollama Host”的配置项。这个设计很巧妙，它意味着Raycast内部已经实现了一套与Ollama服务器通信的协议。

raycast-ai-openrouter-proxy项目正是钻了这个“空子”。它没有去破解或修改Raycast本身，而是选择“扮演”一个Ollama服务器。当你在Raycast设置里将Ollama主机指向localhost:11435（代理服务器的默认端口）时，Raycast就会以为自己在和一个真正的Ollama实例对话，并按照Ollama的API格式发送请求。

此时，代理服务器的核心工作就开始了：

1. 协议解析与转换：代理接收到Raycast发来的、符合Ollama API格式的请求（比如/api/chat）。
2. 请求翻译：它将这个请求体中的消息历史、参数（如temperature）等，重新组装成目标AI服务商（默认为OpenRouter）所期望的OpenAI兼容格式的请求。
3. 转发与鉴权：代理使用你在配置文件中预先设置好的API密钥，将翻译后的请求发送到真正的AI服务商端点（如https://openrouter.ai/api/v1）。
4. 响应回译：收到AI服务商的响应后，代理再将其转换回Ollama API的格式，并流式地返回给Raycast。

整个过程中，你的API密钥和所有的对话数据都只存在于你的本地机器和AI服务商之间，不会经过Raycast的服务器，这在隐私和控制权上是巨大的优势。项目的Docker化部署又保证了环境的一致性，避免了因本地Python或Node.js环境差异导致的“在我机器上能跑”的问题。

2.1 为什么选择OpenRouter作为默认后端？

原作者将OpenRouter设为默认后端，这是一个非常务实且对用户友好的选择。OpenRouter本身就是一个聚合了数十家AI模型提供商（包括OpenAI、Anthropic、Google、Meta等）的API平台。它的核心优势在于：

• 统一接口：无论你想调用GPT-4、Claude还是Gemini，都使用同一套OpenAI兼容的API，极大简化了代理服务器的实现逻辑。
• 按需付费与统一计费：你只需要在OpenRouter上充值，就可以按Token用量调用几乎所有主流模型，账单清晰，无需为每个服务商单独管理密钥和账单。
• 模型发现便捷：OpenRouter的模型市场让你可以轻松比较不同模型的价格和性能，并快速获取其对应的模型ID用于配置。

当然，这个代理的灵活性正在于此。如果你更信任某家服务商，或者有免费的API额度（比如某些云平台提供的OpenAI额度），你完全可以修改配置，将BASE_URL直接指向https://api.openai.com/v1或https://api.anthropic.com/v1等，秒变专属的“OpenAI代理”或“Claude代理”。

3. 从零开始的完整部署与配置指南

理论讲清楚了，我们直接上手。整个过程就像搭积木，只要按步骤来，几乎不会出错。

3.1 前期准备：环境与密钥

首先，确保你的电脑上已经安装了Docker和Docker Compose。在终端输入docker --version和docker compose version检查一下。没有安装的话，去Docker官网下载桌面版，这是最省事的方式。

接下来，获取API密钥。这里以OpenRouter为例，因为它最通用：

1. 访问 OpenRouter官网 并注册账号。
2. 在控制台页面，找到“API Keys”部分，创建一个新的密钥。
3. 重要：新账号通常有免费额度，但为了后续使用，建议在“Billing”页面绑定一张信用卡或进行小额充值（如5美元），否则可能无法调用某些付费模型。OpenRouter的定价是透明的按Token计费，小额充值足以体验很久。

如果你决定使用其他服务商，如OpenAI、Anthropic或Google AI Studio，也请相应地在它们的平台上创建API密钥。

3.2 部署代理服务器

打开终端，我们开始部署。

# 1. 克隆项目仓库到本地 git clone https://github.com/miikkaylisiurunen/raycast-ai-openrouter-proxy.git cd raycast-ai-openrouter-proxy # 2. 编辑Docker Compose配置文件 # 使用你熟悉的文本编辑器，比如VSCode、Vim或Nano code docker-compose.yml # 或者 vim docker-compose.yml

现在，我们来仔细看看并修改docker-compose.yml文件。它的核心部分如下：

version: '3.8' services: raycast-ai-proxy: build: . container_name: raycast-ai-proxy ports: - "11435:8000" # 左边11435是映射到你主机的端口，右边8000是容器内部端口 environment: - BASE_URL=https://openrouter.ai/api/v1 # 目标API的基础URL - API_KEY=YOUR_API_KEY_HERE # 你的API密钥 - MODELS_FILE=/app/models.json # 模型配置文件路径 volumes: - ./models.json:/app/models.json # 将本地的models.json挂载到容器内

你需要做两处关键修改：

1. 替换API密钥：将YOUR_API_KEY_HERE替换为你从OpenRouter（或其他服务商）获取的真实密钥。务必确保密钥被正确包裹在引号内。
2. （可选）更换服务商：如果你不想用OpenRouter，想直接用OpenAI，那么将BASE_URL改为https://api.openai.com/v1，同时API_KEY也换成OpenAI的密钥即可。其他如Anthropic (https://api.anthropic.com/v1)、Google (https://generativelanguage.googleapis.com/v1beta) 同理。

注意：关于端口11435，这是项目默认的，如果这个端口和你电脑上其他服务冲突了（比如某些开发服务器），你可以把左边的主机端口改成其他未被占用的端口，例如- “11436:8000”。记住你修改后的端口号，后面Raycast配置要用。

保存并关闭编辑器。接下来，我们还需要配置模型列表。

3.3 深度定制模型列表：打造你的专属AI工具箱

项目根目录下有一个models.json文件，这是代理服务器的“模型菜单”。Raycast里能看见、能选择哪些模型，完全由这个文件决定。我们打开它，并理解每个参数的意义。

[ { "name": "GPT-4o Mini", "id": "openai/gpt-4o-mini", "contextLength": 128000, "capabilities": ["vision", "tools"], "temperature": 0.7, "max_tokens": 4096 } ]

• name: 在Raycast AI模型下拉列表中显示的名称。你可以起任何方便你识别的名字，比如“快思手- Claude 3.5”。
• id:这是最关键的一环。它必须是你使用的后端服务商能识别的模型标识符。
  • 对于OpenRouter：格式为提供商/模型名，如openai/gpt-4o,anthropic/claude-3-5-sonnet-20241022,google/gemini-2.0-flash-exp。你需要去OpenRouter的模型列表页面查找准确的ID。
  • 对于直接使用OpenAI：直接使用gpt-4o,gpt-4o-mini。
  • 对于直接使用Anthropic：使用claude-3-5-sonnet-20241022。
• contextLength: 模型支持的上下文长度（Token数）。这个数字不会影响模型实际的处理能力，但会影响Raycast UI的显示（比如它可能会根据这个值来估算消耗）。建议设置成模型真实支持的值，可以从服务商文档中查到。设得不准不影响使用，但可能影响Raycast的Token计数显示。
• capabilities: 定义模型的能力。
  • "vision"：如果模型支持图像识别（如GPT-4V, Claude 3, Gemini），必须加上此项。这样Raycast的附件按钮才会允许你上传图片。
  • "tools"：如果模型支持函数调用（Tool Calling），并且你希望在Raycast中使用AI Extensions（如计算器、网页搜索等）或MCP服务器，必须加上此项。注意：这需要在Raycast设置中额外开启一个实验性选项。
• temperature,topP,max_tokens: 这些是直接传递给AI服务商的生成参数，用于控制回复的随机性、集中性和最大长度。你可以为不同模型设置不同的默认值。

我个人的models.json配置参考，专注于性价比和不同场景：

[ { "name": "⚡ Gemini 2 Flash (快)", "id": "google/gemini-2.0-flash-exp", "contextLength": 1000000, "capabilities": ["vision", "tools"], "temperature": 0.8, "max_tokens": 8192 }, { "name": "🤔 Claude 3.5 Sonnet (深思)", "id": "anthropic/claude-3-5-sonnet-20241022", "contextLength": 200000, "capabilities": ["vision", "tools"], "temperature": 0.4, "max_tokens": 4096 }, { "name": "🎯 GPT-4o (精准)", "id": "openai/gpt-4o", "contextLength": 128000, "capabilities": ["vision", "tools"], "temperature": 0.2 }, { "name": "💎 DeepSeek V3 (长文)", "id": "deepseek/deepseek-chat", "contextLength": 128000, "capabilities": ["tools"], "max_tokens": 8192 } ]

配置好后，保存文件。

3.4 启动服务与配置Raycast

回到终端，在项目目录下，运行以下命令来构建并启动代理：

docker compose up -d --build

-d参数让容器在后台运行，--build会确保使用最新的代码构建镜像。第一次运行会下载Python基础镜像和安装依赖，稍等片刻。

看到✔ Container raycast-ai-proxy Started类似的提示后，说明服务已经跑起来了。你可以用docker compose logs查看实时日志，或者docker compose ps确认容器状态。

现在，打开Raycast应用 (⌘ + Space)，进入Raycast Settings->Advanced->AI。你会看到“Ollama Host”的选项。将其设置为http://localhost:11435（如果你修改了端口，请换成http://localhost:你修改的端口）。

关键一步：向下滚动，找到“Enable AI Extensions for Ollama Models (Experimental)”这个选项，并勾选它。只有勾选了这个，你在models.json里为模型配置的"tools"能力才会生效，才能使用那些增强型的AI扩展功能。

设置完成后，随便打开一个需要AI的地方，比如AI Chat命令。你应该能在模型选择下拉列表中，看到你在models.json里配置的那些模型名字了。选择其中一个，开始对话吧！

4. 高级功能配置与疑难排错实录

基础功能跑通后，我们可以探索一些更进阶的用法，并解决可能遇到的问题。

4.1 启用AI扩展与MCP服务器

Raycast的AI Extensions（如Web Search, Calculator）和Model Context Protocol (MCP) 服务器能极大增强AI的能力。要让它们通过我们的代理工作，需要确保两点：

1. 模型配置中包含了"tools"能力。
2. Raycast设置中已开启“Enable AI Extensions for Ollama Models (Experimental)”。

开启后，当你使用支持工具调用的模型（如GPT-4o, Claude 3.5）时，AI就可以根据你的指令，自动调用这些扩展。例如，你可以说“今天旧金山的天气如何？”，AI可能会调用“Web Search”扩展来获取实时信息。

实操心得：目前，并非所有官方AI扩展都能完美兼容。像“Image Generation”这类被归类为“远程工具”的扩展可能无法使用。社区正在积极适配。一个很好的替代方案是使用MCP服务器，你可以寻找或自己搭建提供类似功能（如搜索、画图）的MCP服务。

4.2 利用extra字段进行提供商高级配置

models.json中的extra字段是一个强大的后门，它允许你将任意参数直接传递给后端API。这对于一些提供商特有的功能至关重要。

案例：启用OpenRouter上模型的“思考过程”显示一些模型在OpenRouter上支持“思考过程”（Reasoning Effort），这能让模型在输出最终答案前，先展示其推理链。在Raycast中，这表现为模型输出时会先有一段“思考中...”的段落。要启用它，你需要查阅OpenRouter的文档，找到对应模型的参数。通常配置如下：

{ "name": "Claude 3.5 Sonnet (思考模式)", "id": "anthropic/claude-3-5-sonnet-20241022", "contextLength": 200000, "capabilities": ["vision", "tools"], "extra": { "reasoning": { "effort": "high", // 或 "medium", "low" "max_tokens": 4096 // 限制思考部分的最大token数 } } }

案例：在OpenRouter上指定首选模型提供商同一个模型ID（如openai/gpt-4o）在OpenRouter背后可能有多个提供商（如OpenAI官方、Azure等）。你可以使用extra来锁定一个：

{ "name": "GPT-4o (仅限官方)", "id": "openai/gpt-4o", "contextLength": 128000, "capabilities": ["vision", "tools"], "extra": { "provider": { "only": ["openai"] // 只使用OpenAI官方提供的服务 } } }

重要提示：extra字段的内容不会被代理服务器验证。如果配置错误，请求会直接失败。排查这类问题时，第一件事就是查看Docker容器的日志 (docker compose logs)，里面通常会包含来自后端API的详细错误信息。

4.3 常见问题与解决方案速查表

在实际使用中，你可能会遇到以下问题。别慌，大部分都有解。

问题现象	可能原因	排查步骤与解决方案
Raycast中看不到任何模型	1. 代理服务器未启动。 2. Raycast配置的端口错误。 3.models.json格式错误。	1. 运行docker compose ps确认容器状态为Up。 2. 运行docker compose logs查看启动日志，确认无报错。 3. 检查Raycast中Ollama Host的地址和端口是否与docker-compose.yml中ports映射的左端口一致。 4. 使用 JSON格式验证工具 检查models.json文件。
选择模型后，回复一直“加载中”或报错	1. API密钥错误或过期。 2. 网络问题（如代理冲突）。 3. 模型id填写错误。 4. 账户余额不足。	1.查看日志：docker compose logs是最直接的排错手段，错误信息会明确指出是认证失败、模型不存在还是额度不足。 2. 确认API密钥在docker-compose.yml中已正确替换且未被截断。 3. 前往OpenRouter等提供商后台，确认模型ID拼写正确，且账户有足够额度或已绑定支付方式。 4. 如果你使用了网络代理，可能需要配置Docker容器使用宿主机的代理。
无法上传图片（Vision功能失效）	1. 模型配置中未添加"vision"能力。 2. 当前选择的模型本身不支持视觉识别。	1. 检查models.json中对应模型的capabilities数组是否包含"vision"。 2. 确认你选择的模型（如GPT-4o, Claude 3.5, Gemini）确实支持视觉功能。GPT-3.5就不支持。
AI扩展（工具调用）不工作	1. 模型配置中未添加"tools"能力。 2. Raycast中未开启实验性功能开关。 3. 该扩展属于不支持的“远程工具”。	1. 检查models.json中对应模型的capabilities数组是否包含"tools"。 2.务必进入Raycast设置 -> AI，勾选“Enable AI Extensions for Ollama Models (Experimental)”。 3. 尝试使用其他扩展（如Calculator），或考虑使用MCP服务器替代。
修改models.json后，Raycast中无变化	修改未生效到Docker容器中。	每次修改models.json后，必须重启容器：docker compose restart。
想更换API提供商	配置需要更新。	1. 修改docker-compose.yml中的BASE_URL和API_KEY。 2. 同步更新models.json中所有模型的id为对新提供商有效的ID。 3. 运行docker compose up -d --build重建并重启服务。

4.4 性能优化与安全考量

性能：由于代理在本地运行，延迟主要取决于你的网络到AI服务商服务器的速度。对于日常文本交互，感知不明显。如果你需要进行大量的流式输出，确保本地Docker资源分配充足。

安全：项目目前没有内置身份验证。这意味着任何能访问http://你的电脑IP:11435的人，都可以使用你的代理（进而消耗你的API额度）。因此：

1. 强烈不建议将其部署在公网可访问的服务器上，除非你通过防火墙严格限制访问IP，或者自己在代理前加一层身份验证（如Nginx Basic Auth）。
2. 在本地使用是安全的，因为默认绑定在127.0.0.1(localhost)，只有本机可以访问。
3. 妥善保管你的docker-compose.yml文件，因为它里面明文存储了你的API密钥。可以考虑使用Docker的密钥管理功能或环境变量文件来更安全地管理密钥。

我个人习惯将API密钥放在一个单独的.env文件中，并在docker-compose.yml里通过env_file引入，这样docker-compose.yml文件本身就可以安全地提交到Git仓库进行版本管理。具体做法是：

1. 创建.env文件：echo “API_KEY=your_real_key_here” > .env
2. 修改docker-compose.yml，将environment部分改为引用环境变量，并添加env_file：

   environment: - BASE_URL=https://openrouter.ai/api/v1 - API_KEY=${API_KEY} # 从环境变量读取 - MODELS_FILE=/app/models.json env_file: - .env # 指定环境变量文件

3. 将.env添加到.gitignore文件中，确保密钥不会意外上传。

经过以上步骤，你就拥有了一个完全受自己控制、功能强大且高度可定制的Raycast AI伴侣。它打破了订阅墙，将模型选择权彻底交还给你。无论是追求极致性价比的日常问答，还是需要复杂推理和工具调用的深度任务，你都可以通过简单的配置文件切换来调用最合适的模型。这种自由度和掌控感，正是开源项目和自托管方案最吸引人的地方。