⚙️ 配置指南
macOS 未签名二进制处理 · API Key 配置 · 支持的模型与供应商
1. macOS 未签名二进制问题
从 GitHub Releases 下载的 youcoder-macos-arm64.dmg 或 youcoder-macos-x64.dmg 是磁盘映像文件，需要挂载后提取其中的二进制：
⚠ 问题现象：
直接双击 DMG 可能提示 "Apple could not verify 'youcoder-macos-x64.dmg' is free of malware"。
直接双击 DMG 可能提示 "Apple could not verify 'youcoder-macos-x64.dmg' is free of malware"。
解决方法：用命令行挂载 DMG、提取二进制、移除 quarantine 属性：
# 1. 挂载 DMG（会挂载到 /Volumes/YouCoder/） hdiutil attach ./youcoder-macos-arm64.dmg # 2. 复制二进制到当前目录 cp /Volumes/YouCoder/youcoder-macos-arm64 ./ # 3. 卸载 DMG hdiutil detach /Volumes/YouCoder # 4. 移除 quarantine 属性 xattr -d com.apple.quarantine ./youcoder-macos-arm64 # 5. 赋予执行权限 chmod +x ./youcoder-macos-arm64 # 6. 运行 ./youcoder-macos-arm64
如果仍被拦截，去 系统设置 → 隐私与安全性，手动允许该应用。
2. 配置 API Key 和模型
YouCoder 支持三种配置方式，优先级从高到低：
| 优先级 | 方式 | 说明 |
|---|---|---|
| 1（最高） | CLI 参数 | 临时生效，每次运行都要指定 |
| 2 | 环境变量 | 当前 Shell 会话生效 |
| 3（最低） | 配置文件 | 持久化，推荐 |
2.1 方式一：CLI 参数
./youcoder-macos-arm64 --provider deepseek --api-key sk-your-key --model deepseek-v4-pro
| 参数 | 说明 |
|---|---|
--provider | 供应商（anthropic / openai / deepseek） |
--api-key | API Key |
--model | 模型名 |
--base-url | 自定义 API 地址（可选） |
--max-tokens | 最大响应 Token 数 |
--search-provider | 搜索供应商（duckduckgo / bing） |
--proxy-url | HTTP 代理地址 |
2.2 方式二：环境变量
# DeepSeek（推荐，自动识别 provider） export DEEPSEEK_API_KEY=sk-your-key ./youcoder-macos-arm64 # Anthropic Claude export ANTHROPIC_API_KEY=sk-ant-your-key ./youcoder-macos-arm64 # OpenAI export OPENAI_API_KEY=sk-your-key ./youcoder-macos-arm64 # 通用变量（可覆盖以上所有） export YOUCODER_PROVIDER=deepseek export YOUCODER_API_KEY=sk-your-key export YOUCODER_MODEL=deepseek-v4-pro export YOUCODER_BASE_URL=https://api.deepseek.com ./youcoder-macos-arm64
| 环境变量 | 说明 |
|---|---|
ANTHROPIC_API_KEY | 自动设置 provider = anthropic |
OPENAI_API_KEY | 自动设置 provider = openai |
DEEPSEEK_API_KEY | 自动设置 provider = deepseek |
YOUCODER_PROVIDER | 强制指定供应商 |
YOUCODER_API_KEY | 通用 API Key |
YOUCODER_MODEL | 模型名 |
YOUCODER_BASE_URL | 自定义 API 地址 |
YOUCODER_PROXY_URL | HTTP 代理 |
YOUCODER_MAX_TOKENS | 最大 Token 数 |
2.3 方式三：配置文件（推荐）
配置文件路径因操作系统而异：
| 系统 | 配置文件路径 |
|---|---|
| macOS | ~/Library/Application Support/youcoder/config.toml |
| Linux | ~/.config/youcoder/config.toml |
| Windows | %APPDATA%\youcoder\config.toml |
创建配置文件：
# macOS 示例 mkdir -p ~/Library/Application\ Support/youcoder cat > ~/Library/Application\ Support/youcoder/config.toml << 'EOF' # 供应商: deepseek / anthropic / openai provider = "deepseek" # API Key api_key = "sk-your-key" # 模型名 model = "deepseek-v4-pro" # 可选：自定义 API 地址 # base_url = "https://api.deepseek.com" # 可选：HTTP 代理 # proxy_url = "http://127.0.0.1:7890" EOF
也可以在项目根目录创建 .youcoder/config.toml，仅对当前项目生效（优先级高于全局配置，低于环境变量和 CLI 参数）。
2.4 支持的供应商与模型
| 供应商 | provider 值 | 常用模型 |
|---|---|---|
| Anthropic | anthropic | claude-sonnet-4-20250514 |
| OpenAI | openai | gpt-4o / o3-mini |
| DeepSeek | deepseek | deepseek-v4-pro |
3. 快速验证
配置完成后，启动 YouCoder 进入 TUI 界面即表示成功。如需验证 API Key 是否生效，查看日志：
# 日志文件路径 ~/.youcoder/logs/ # 查看最新日志 tail -f ~/.youcoder/logs/youcoder-$(date +%Y-%m-%d).log
4. 常见问题
Q: 配置文件写对了还是提示 "No API key configured"？
确认文件位置是否正确。macOS 用户常见的错误是把配置文件放在了 ~/.config/youcoder/config.toml，实际应为 ~/Library/Application Support/youcoder/config.toml：
# macOS 检查配置文件 ls -la ~/Library/Application\ Support/youcoder/config.toml # 或直接用环境变量方式 export DEEPSEEK_API_KEY=sk-your-key ./youcoder-macos-arm64
Q: 一直提示不安全无法运行？
运行 xattr -d com.apple.quarantine ./youcoder-macos-arm64。若仍不行，去 系统设置 → 隐私与安全性，手动允许。
Q: 如何切换到其他供应商？
修改配置文件的 provider 和 api_key 字段，或通过环境变量 YOUCODER_PROVIDER 覆盖。若设为 auto，程序会根据环境变量前缀自动识别。
Q: 配置文件里 API Key 是明文，安全吗？
配置文件放在用户私有目录下（仅当前用户可读），权限为 600。如果你使用共享机器，建议使用环境变量方式，每次会话手动 export。