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格式发送请求。此时代理服务器的核心工作就开始了协议解析与转换代理接收到Raycast发来的、符合Ollama API格式的请求比如/api/chat。请求翻译它将这个请求体中的消息历史、参数如temperature等重新组装成目标AI服务商默认为OpenRouter所期望的OpenAI兼容格式的请求。转发与鉴权代理使用你在配置文件中预先设置好的API密钥将翻译后的请求发送到真正的AI服务商端点如https://openrouter.ai/api/v1。响应回译收到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为例因为它最通用访问 OpenRouter官网 并注册账号。在控制台页面找到“API Keys”部分创建一个新的密钥。重要新账号通常有免费额度但为了后续使用建议在“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_URLhttps://openrouter.ai/api/v1 # 目标API的基础URL - API_KEYYOUR_API_KEY_HERE # 你的API密钥 - MODELS_FILE/app/models.json # 模型配置文件路径 volumes: - ./models.json:/app/models.json # 将本地的models.json挂载到容器内你需要做两处关键修改替换API密钥将YOUR_API_KEY_HERE替换为你从OpenRouter或其他服务商获取的真实密钥。务必确保密钥被正确包裹在引号内。可选更换服务商如果你不想用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的能力。要让它们通过我们的代理工作需要确保两点模型配置中包含了tools能力。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额度。因此强烈不建议将其部署在公网可访问的服务器上除非你通过防火墙严格限制访问IP或者自己在代理前加一层身份验证如Nginx Basic Auth。在本地使用是安全的因为默认绑定在127.0.0.1(localhost)只有本机可以访问。妥善保管你的docker-compose.yml文件因为它里面明文存储了你的API密钥。可以考虑使用Docker的密钥管理功能或环境变量文件来更安全地管理密钥。我个人习惯将API密钥放在一个单独的.env文件中并在docker-compose.yml里通过env_file引入这样docker-compose.yml文件本身就可以安全地提交到Git仓库进行版本管理。具体做法是创建.env文件echo “API_KEYyour_real_key_here” .env修改docker-compose.yml将environment部分改为引用环境变量并添加env_fileenvironment: - BASE_URLhttps://openrouter.ai/api/v1 - API_KEY${API_KEY} # 从环境变量读取 - MODELS_FILE/app/models.json env_file: - .env # 指定环境变量文件将.env添加到.gitignore文件中确保密钥不会意外上传。经过以上步骤你就拥有了一个完全受自己控制、功能强大且高度可定制的Raycast AI伴侣。它打破了订阅墙将模型选择权彻底交还给你。无论是追求极致性价比的日常问答还是需要复杂推理和工具调用的深度任务你都可以通过简单的配置文件切换来调用最合适的模型。这种自由度和掌控感正是开源项目和自托管方案最吸引人的地方。