> ## 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`  | 用于账户级命令的访问令牌                                    |
| `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

可选。以下账户级命令需要 access token：`account`、`stats`、`tokens`、`logs` 和 `tasks`。

在 [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` 添加一个 |