WorkBuddy的所有自定义模型密钥必须手动写入~/.workbuddy/models.json，修改后需完全退出重启才能生效。 一份能直接复制的配置示例 json { "models": [ { "id": "azure-gpt-4o", "name": "Azure GPT-4o", "vendor": "Azure OpenAI", "apiKey": "${AZURE_OPENAI_API_KEY}", "url": "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT_NAME/chat/completions?api-version=2024-10-21", "maxInputTokens": 128000, "maxOutputTokens": 16384, "temperature": 0.7, "supportsToolCall": true, "supportsImages": true } ], "availableModels": ["azure-gpt-4o"] } 四步完成配置 第一步：执行mkdir -p ~/.workbuddy创建目录，路径必须是~/.workbuddy/models.json。 第二步：将YOUR_RESOURCE_NAME替换为Azure OpenAI资源名称，YOUR_DEPLOYMENT_NAME替换为部署名称。 第三步：设置API Key。推荐在~/.zshrc中添加export AZURE_OPENAI_API_KEY="你的密钥"，或在apiKey字段直接写入明文。 第四步：完全退出WorkBuddy再重新启动，不支持热重载。 多模型扩展示例 如需同时配置多个模型，按以下格式： json { "models": [ { "id": "azure-gpt-4o", "name": "Azure GPT-4o", "vendor": "Azure OpenAI", "apiKey": "${AZURE_OPENAI_API_KEY}", "url": "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-10-21", "maxInputTokens": 128000, "maxOutputTokens": 16384, "temperature": 0.7, "supportsToolCall": true, "supportsImages": true }, { "id": "azure-gpt-4o-mini", "name": "Azure GPT-4o Mini", "vendor": "Azure OpenAI", "apiKey": "${AZURE_OPENAI_API_KEY}", "url": "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/gpt-4o-mini/chat/completions?api-version=2024-10-21", "maxInputTokens": 128000, "maxOutputTokens": 16384, "temperature": 0.7, "supportsToolCall": true, "supportsImages": true } ], "availableModels": ["azure-gpt-4o", "azure-gpt-4o-mini"] }

Azure OpenAI与标准OpenAI的最大区别在于URL结构——部署名称必须嵌入路径，且WorkBuddy使用apiKey头认证，而非Bearer令牌。 必填字段详解 id：模型唯一标识符，WorkBuddy内部用于识别。建议使用azure-gpt-4o等有含义的命名，同一文件内不可重复。 apiKey：Azure OpenAI的API密钥。推荐使用环境变量引用格式${变量名}，避免密钥明文暴露。 url：最关键的字段。格式必须是https://{资源名}.openai.azure.com/openai/deployments/{部署名}/chat/completions?api-version={版本号}。WorkBuddy要求URL中必须包含部署名称，这与标准OpenAI完全不同——后者只需在请求体中写模型名。API版本建议用2024-10-21。 supportsToolCall：设为true可启用Function Calling能力，Azure OpenAI支持该功能。 可选字段说明 name：在WorkBuddy界面下拉菜单中显示的名称，不填则显示id。 vendor：建议填Azure OpenAI，便于日志识别。 maxInputTokens：最大输入Token数，GPT-4o系列为128000。 maxOutputTokens：最大输出Token数，建议16384。 temperature：采样温度，范围0-2，日常用0.7。 supportsImages：设为true启用多模态图像识别。 availableModels字段 这是一个字符串数组，控制WorkBuddy界面下拉列表中显示哪些模型。未在列表中出现的模型不会被展示。 Azure认证的特殊性 该系统使用api-key HTTP头进行认证，而非标准OpenAI的Bearer。WorkBuddy的url字段已按OpenAI兼容格式设计，认证方式由apiKey字段自动适配，无需额外配置。

配置完成后模型无法调用，90%以上的原因是URL格式错误或JSON语法问题，而非API密钥本身无效。 问题一：URL格式错误 正确的URL格式必须是https://{资源名}.openai.azure.com/openai/deployments/{部署名}/chat/completions?api-version={版本号}。 典型错误：写成https://api.openai.com/v1（那是标准OpenAI的端点），或漏掉/deployments/{部署名}路径段。请核对Azure门户中的资源名和部署名。 问题二：部署名称与模型名称混淆 WorkBuddy配置中的id可自定义，但URL中的部署名称必须与Azure中实际创建的部署名称完全一致。Azure始终要求使用部署名称，而非模型名称。 检查方法：登录Azure门户，进入Azure OpenAI资源，查看“部署”列表中的名称，将其填入URL。 问题三：JSON格式错误导致解析失败 末尾多了一个逗号或使用了中文标点，会导致WorkBuddy启动时模型列表为空。可使用在线JSON验证工具或执行cat ~/.workbuddy/models.json | python -m json.tool校验。 问题四：配置文件位置错误 路径必须是~/.workbuddy/models.json，且修改后必须完全退出WorkBuddy再重启，不支持热重载。 问题五：API版本号不兼容 推荐使用2024-10-21或更新版本。如果调用返回版本相关错误，尝试更新api-version参数。 问题六：环境变量未正确加载 使用环境变量引用格式${VAR_NAME}时，需确保变量在WorkBuddy启动前已设置并导出。先执行echo $AZURE_OPENAI_API_KEY确认值存在，再从同一终端启动WorkBuddy。 总结：以上配置示例和方法完全基于WorkBuddy的官方配置规则。只要严格遵循URL格式和部署名称要求，并在修改后完全重启，即可顺利接入Azure OpenAI。如果仍遇到问题，建议优先检查JSON语法和URL中的部署名称是否与Azure门户完全一致。