> ## Documentation Index
> Fetch the complete documentation index at: https://apidoc.cometapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 設定

> 設定 CometAPI CLI：設定檔位置、可用設定、憑證管理、環境變數與安全性實務。

CometAPI CLI 會從 TOML 設定檔、環境變數與命令列旗標讀取設定。當同一個設定可從多個來源取得時，其優先順序如下：

**CLI 旗標 > 設定檔 > 環境變數 > 預設值**

## 設定檔

位置：`~/.config/cometapi/config.toml`

執行設定精靈，以互動方式建立設定檔：

```bash theme={null}
cometapi init
```

或者使用 `config` 子命令管理個別設定：

```bash theme={null}
# View current configuration
cometapi config show

# Set a value
cometapi config set api_key "$COMETAPI_KEY"

# Remove a value
cometapi config unset api_key

# Show the config file path
cometapi config path
```

## 可用設定

| 設定鍵             | 環境變數                     | 說明                                              |
| --------------- | ------------------------ | ----------------------------------------------- |
| `api_key`       | `COMETAPI_KEY`           | API key（所有命令皆必填）                                |
| `access_token`  | `COMETAPI_ACCESS_TOKEN`  | 用於帳戶層級命令的 access token                          |
| `base_url`      | `COMETAPI_BASE_URL`      | API 基底 URL（預設：`https://api.cometapi.com/v1`）    |
| `default_model` | `COMETAPI_DEFAULT_MODEL` | `chat` 與 `run` 的預設 model（後備值：`gpt-5.4`）         |
| `output_format` | —                        | 預設輸出格式：`table`、`json`、`yaml`、`csv` 或 `markdown` |

## 憑證

CLI 使用兩種類型的憑證：

### API key

所有命令都需要。API key 用於驗證發送至 CometAPI 模型端點的請求。

在 [CometAPI Console → API Keys](https://www.cometapi.com/console/token) 建立 API key。

可用以下其中一種方式設定：

<CodeGroup>
  ```bash Environment variable theme={null}
  read -rsp "CometAPI API key: " COMETAPI_KEY
  printf '\n'
  export COMETAPI_KEY
  ```

  ```bash Config file theme={null}
  cometapi config set api_key "$COMETAPI_KEY"
  ```

  ```bash Setup wizard theme={null}
  cometapi init
  ```
</CodeGroup>

### Access token

選填。帳戶層級命令 `account`、`stats`、`tokens`、`logs` 與 `tasks` 需要 access token。

在 [CometAPI Console → Personal Settings](https://www.cometapi.com/console/personal) 產生 access token。

可用以下其中一種方式設定：

<CodeGroup>
  ```bash Environment variable theme={null}
  export COMETAPI_ACCESS_TOKEN="your-access-token"
  ```

  ```bash Config file theme={null}
  cometapi config set access_token your-access-token
  ```

  ```bash Setup wizard theme={null}
  cometapi init
  ```
</CodeGroup>

## 安全性

CLI 採用以下安全性實務：

* API key 與 access token 不會被記錄或完整顯示。診斷輸出中只會顯示最後 4 個字元。
* 設定檔會以限制性權限（`0600`）建立——只有檔案擁有者可讀取。
* 憑證絕不應提交到版本控制。如果適用，請將設定檔路徑加入你的 `.gitignore`。

<Warning>
  你需對使用你的 API key 所產生的所有用量與費用負責。請妥善保護你的金鑰，若懷疑有未經授權的存取，請輪替金鑰。
</Warning>

## 疑難排解

| 錯誤                            | 解決方案                                                                    |
| ----------------------------- | ----------------------------------------------------------------------- |
| `API key not configured`      | 執行 `cometapi init` 或設定 `COMETAPI_KEY` 環境變數                              |
| `Connection failed`           | 執行 `cometapi doctor` 以診斷連線能力                                            |
| `Access token not configured` | 僅 `account`/`stats`/`tokens`/`logs`/`tasks` 需要。執行 `cometapi init` 以新增一個 |