Connections and per-project settings

Basic concepts

Agent Switchboard manages three things separately.

• Connection: The address and API key of a gateway or provider. Add it once under 환경 설정 › 연결 · 인증 (Settings › Connections · Authentication), and multiple tools can choose the same connection. Tools that use the same connection share its key.
• Tool: A coding agent CLI such as Codex, Claude Code, or Pi. For each tool, you set the connection method (API / 게이트웨이 (API / Gateway) or OAuth / 기본 인증 (OAuth / Default authentication)), model, and reasoning effort.
• Scope: The 전역 기본 (Global default) is the value every registered folder follows. If you save settings separately in a folder, folder-specific values apply to that folder only.

A folder without its own settings uses the global default as is. The first time you save in a folder, the current values are used as the starting point for that folder's own settings. Folder-specific provider, authentication, model, and reasoning settings take precedence over the global ones.

Supported connections

Connections are also managed for Droid, Crush, and Kimi Code. Antigravity (agy), Copilot CLI, Cursor CLI, Amp, Goose, Aider, Kilo CLI, Grok Build, and Gemini CLI are supported for installation detection and launching only. Each of these tools manages its own settings and authentication.

Adding connections

API keys and gateways

1. Open 환경 설정 (Settings) at the bottom of the sidebar and go to 연결 · 인증 (Connections · Authentication).
2. Click 연결 추가 (Add connection).
3. Choose a service from the provider catalog or enter a gateway address, enter the API key, and save.

Remote addresses must use HTTPS. HTTP is allowed only for addresses on the same PC (loopback).

Keys are stored encrypted per connection in the operating system's secure storage (Windows DPAPI, macOS Keychain, Linux Secret Service). Saved keys are never shown on screen again. Only Agent Switchboard's credential helper command, not the key, is written to Codex, Claude Code, and Pi settings files. When a tool runs, the helper retrieves the key from secure storage and passes it on.

Adding a connection does not apply it to any tool by itself. Apply it to a tool by following the steps in the next section.

Subscription login (OAuth)

When you use a tool's own login, such as a ChatGPT or Claude subscription, no API key is needed.

1. On the tool settings screen, choose OAuth / 기본 인증 (OAuth / Default authentication).
2. Click 기본 인증 적용 (Apply default authentication).
3. Sign in through the tool's login flow.

Each CLI stores and refreshes its OAuth tokens in its own storage. Agent Switchboard does not read or copy these tokens.

Using multiple accounts

Codex, Claude Code, Pi, and Qwen Code can use default authentication with multiple accounts. Create an account in the tool's account list and sign in, then choose the account globally or per project. For Pi, sign in with /login in an open terminal; for Qwen Code, use /auth. Account selection does not apply to API and gateway connections.

Applying to tools

Global default

1. Click 전역 기본 (Global default) in the left rail. You can also open it with 전역 기본과 비교 (Compare with global default) on the project home.
2. Click a tool card to open its settings screen.
3. Choose API / 게이트웨이 (API / Gateway) or OAuth / 기본 인증 (OAuth / Default authentication).
4. For an API connection, choose a connection you added, then choose a model from the searchable list. When you change the model, the reasoning effort levels and token limits that model supports are applied along with it.
5. Use 연결 테스트 (Test connection) to check the address and authentication.
6. Click 저장 후 적용 (Save and apply). For OpenCode, click 설정 적용 (Apply settings).

During the connection test and when applying, the app checks whether the selected model can actually be used. If it cannot, the change is not applied and you are notified. In that case, choose a usable model from the list yourself.

Different settings for each project folder

This is the core feature of Agent Switchboard. Even on the same PC, each folder can use a different agent, model, provider, and key.

1. Choose a project in the left rail to open its project home.
2. In 도구 설정 (Tool settings), click a tool card. To add a tool that is not in the list, use the 도구 (Tools) button (add a tool to show for this folder).
3. Choose the connection method, connection, model, and reasoning effort in the same way as for the global default.
4. When you apply, these become this folder's own settings.

From top to bottom, the project home shows 지금 (Now: running, waiting for input, and errored sessions), Tool settings, and 최근 세션 (Recent sessions). The tool cards show that folder's tool, connection, model, and reasoning effort at a glance. Use Compare with global default to see them side by side with the global values.

Folder-specific settings are written to the following files for each tool.

Cline CLI does not create a project settings file; it runs in the selected folder. Tools that do not support project settings are marked 프로젝트 설정 미지원 (Project settings not supported) and use the PC-wide settings.

Defaults for new Switcher chats

You can also set the default agent, model, and reasoning effort for Switcher chats per folder. In the Switcher menu of a project in the rail, open settings and click 이 폴더에 저장 (Save to this folder). Clicking 전역 기본값 따르기 (Follow global default) clears the folder value and follows the global default again. Chats that are already open keep their existing engine, model, and reasoning effort.

Switching quickly from the tray

Click the tray icon (the menu bar icon on macOS) to open the quick switch panel.

1. Choose a tool, then choose API · 게이트웨이 (API · Gateway) or OAuth · 기본 인증 (OAuth · Default authentication).
2. When you choose a provider, the model list is loaded using the saved connection.
3. Choose a model and click 이 공급자로 전환 (Switch to this provider).

Quick switching goes through the same backup, connection test, and verification steps as the main window.

Settings file protection

• Before changing settings, the original is backed up once the first time, and a revision backup is kept for every change.
• Agent Switchboard changes only the fields it manages and preserves the rest of your settings.
• After applying, the generated files are read back and verified. If verification fails, the changes from that apply are rolled back to the previous state.
• 최초 설정 복원 (Restore original settings) returns files to their state before Agent Switchboard first modified them.
• When you delete a saved key, managed connections are first switched to the tool's default authentication.

Next steps

• To continue on your phone, see Phone connection.
• For the chat interface and coordinating multiple sessions, see Switcher and orchestration.