❓ 常见问题 FAQ

高频问题的快速解答 · 更多细节见各客户端手册

1. 桌面端：登录后显示 Free 版本

问题：我是 Pro 用户，在桌面端登录完成后，界面显示的是 Free 版本。

解决方案：这是桌面端的已知现象——登录后本地许可状态需要一次刷新才会与服务器同步。请使用桌面端的 Reload（重新加载） 功能：

1. 打开桌面端右上角的 设置 / 菜单。
2. 点击 Reload（重新加载 / 刷新）按钮。
3. 界面刷新后即可正常显示 Pro 版本，全部 Pro 功能恢复可用。

2. 提示 "No API key configured"

问题：启动 / 对话时提示没有配置 API Key。

解决方案：YouCoder 需要至少一个模型提供商的 API Key 才能调用大模型：

• 编辑 ~/.youcoder/config.toml，写入 api_key = "sk-xxx"（详见 config.toml 配置教程）。
• 或使用环境变量，如 export DEEPSEEK_API_KEY=sk-xxx。
• TUI 中可用 /status 查看当前配置状态。

3. 桌面端应用无法启动

问题：双击应用没有反应，或启动即闪退。

解决方案：

• 确认安装包与系统架构匹配（Apple Silicon / Intel）。
• 删除 ~/Library/Application Support/youcoder 后重试。
• macOS 首次打开被拦截时，参考第 7 条。

4. 提示 "Engine not running"

问题：桌面端提示引擎未运行。

解决方案：完全退出应用后重新启动；如仍复现，查看 ~/Library/Logs/youcoder/（macOS）中的日志定位原因。

5. 连接不上模型

问题：对话时提示无法连接模型提供商。

解决方案：按顺序检查：

1. API Key 是否正确、账户是否有额度。
2. 网络是否可达（必要时配置 proxy_url，见 配置教程第 4 节）。
3. 模型名是否正确（/model list 查看可用模型）。
4. base_url 是否被误覆盖。

6. 工具执行被拒绝

问题：AI 调用命令工具（如 exec_shell）时被拒绝。

解决方案：检查 [tools.exec] 的安全策略与感知域：

• security = "deny" 时全部命令被禁止，改为 "allowlist" 或 "relaxed"。
• 命令未命中 allowlist 白名单时需手动确认，或把常用命令加入白名单（支持 npm run * 通配）。
• 确认文件在感知域（scope）范围内，越界操作会被拒绝。

详见 配置教程第 6 节。

7. macOS 首次打开被拦截

问题：macOS 提示无法打开 YouCoder，因为来自身份不明的开发者。

解决方案：右键应用图标 → 选择「打开」；或 系统设置 → 隐私与安全性 → 仍要打开。

❓ FAQ Frequently Asked Questions

Quick answers to common issues · more details in each client manual

1. Desktop: Shows Free after logging in

Issue: I'm a Pro user, but after logging in on the desktop app, the UI shows the Free tier.

Solution: This is a known desktop behavior — the local license state needs one refresh to sync with the server. Use the Reload feature:

1. Open Settings / Menu in the top-right corner of the desktop app.
2. Click the Reload button.
3. After the UI refreshes, it should correctly show Pro and all Pro features become available again.

2. "No API key configured"

Issue: YouCoder reports no API key configured at startup or during chat.

Solution: YouCoder needs at least one provider API key to call LLMs:

• Edit ~/.youcoder/config.toml and add api_key = "sk-xxx" (see the config.toml guide).
• Or use an environment variable, e.g. export DEEPSEEK_API_KEY=sk-xxx.
• In the TUI, run /status to inspect the current configuration.

3. Desktop app won't launch

Issue: Double-clicking the app does nothing, or it crashes on startup.

Solution:

• Verify the installer matches your CPU architecture (Apple Silicon / Intel).
• Delete ~/Library/Application Support/youcoder and retry.
• If macOS blocks the first launch, see item 7 below.

4. "Engine not running"

Issue: The desktop app reports the engine is not running.

Solution: Quit the app completely and relaunch; if it persists, check ~/Library/Logs/youcoder/ (macOS) to find the cause.

5. Can't reach the model

Issue: Chat fails with a model-connection error.

Solution: Check in order:

1. The API key is valid and the account has quota.
2. The network is reachable (configure proxy_url if needed, see Config guide §4).
3. The model name is correct (/model list shows available models).
4. base_url is not accidentally overridden.

6. Tool execution denied

Issue: The AI's command-tool calls (e.g. exec_shell) are denied.

Solution: Check the [tools.exec] policy and the perception scope:

• With security = "deny" all commands are blocked — switch to "allowlist" or "relaxed".
• Commands not matching the allowlist need manual confirmation — add frequently used ones (wildcards like npm run * are supported).
• Make sure the file is inside the perception scope (out-of-scope operations are rejected).

See Config guide §6.

7. macOS blocks the first launch

Issue: macOS warns that YouCoder can't be opened because it's from an unidentified developer.

Solution: Right-click the app icon → choose "Open"; or System Settings → Privacy & Security → Open Anyway.