# Claude Code CLI 与终端参考

> Claude Code CLI 命令、安装渠道、环境变量、PATH、终端快捷键、fullscreen、voice dictation、deep links 和缓存影响。

URL: https://docs.passion8.cc/docs/claude-code/cli-terminal-reference
Language: zh-CN
Publisher: Passion8

这页把官方 CLI reference、advanced setup、environment variables、terminal config、keybindings、fullscreen、voice dictation 和 deep links 合成一个速查。安装失败和登录失败仍优先看 [安装与登录排错](https://docs.passion8.cc/docs/claude-code/install-troubleshooting)。

## 常用 CLI

| 命令 | 用途 | 缓存影响 |
| --- | --- | --- |
| `claude` | 打开交互会话 | 新会话或当前目录历史 |
| `claude "task"` | 带初始 prompt 打开交互会话 | 新增首条消息 |
| `claude -p "query"` | 一次性 query 后退出 | 适合 CI,通常新前缀 |
| `cat file | claude -p "query"` | 处理管道输入 | 管道内容进入上下文 |
| `claude -c` | 继续当前目录最近会话 | 更可能复用缓存 |
| `claude -r "<session>"` | 恢复指定 session | 复用该 session 历史 |
| `claude update` | 更新版本 | 不直接影响缓存 |
| `claude install stable` | 安装或重装 native binary | 不直接影响缓存 |
| `claude auth login` | 登录 | 影响 Provider 和账号 |
| `claude auth status` | 查看登录状态 | 无模型调用 |
| `claude agents` | 打开 Agent View | 本机多 session 管理 |
| `claude mcp login <name>` | MCP OAuth 登录 | 工具集变化可能影响缓存 |
| `claude plugin` | 管理插件 | 插件变化可能影响缓存 |
| `claude remote-control` | 启动远程控制 server | 本机会话继续 |
| `claude doctor` | 诊断配置 | 低影响 |

接 Passion8 的最小测试:

```bash
ANTHROPIC_BASE_URL=https://passion8.cc \
ANTHROPIC_AUTH_TOKEN=sk-你的 Passion8 API Key \
claude -p "用一句话回答 ping"
```

## 安装和版本

| 渠道 | 适合 |
| --- | --- |
| 官方 native installer | 大多数本机用户 |
| Homebrew / apt / dnf / apk | 受包管理器管理的机器 |
| npm | 需要 Node 生态或旧部署方式 |
| 指定版本安装 | 企业固定版本或回滚 |
| minimum version pin | 管理员要求最低版本 |
| 禁用 auto-update | 强管控环境 |

Windows 选择:

| 方案 | 适合 |
| --- | --- |
| Native Windows | Windows-native 项目 |
| WSL 2 | Linux toolchain、sandbox、server 项目 |
| WSL 1 | 仅在 WSL 2 不可用时使用 |

安装后验证:

```bash
claude --version
claude doctor
claude auth status --text
```

## 环境变量

| 变量 | 用途 |
| --- | --- |
| `ANTHROPIC_BASE_URL` | Anthropic 兼容 Base URL,Passion8 用 `https://passion8.cc` |
| `ANTHROPIC_AUTH_TOKEN` | OAuth 或兼容网关 token |
| `ANTHROPIC_API_KEY` | API key 认证 |
| `HTTPS_PROXY` / `HTTP_PROXY` | 企业代理 |
| `NO_PROXY` | 跳过代理的域名/IP |
| `NODE_EXTRA_CA_CERTS` | 自定义 CA |
| `CLAUDE_CODE_CLIENT_CERT` | mTLS client cert |
| `CLAUDE_CODE_CLIENT_KEY` | mTLS client key |
| `CLAUDE_CONFIG_DIR` | 隔离配置、transcripts 和本地状态 |
| `CLAUDE_CODE_DISABLE_AUTO_MEMORY` | 禁用 auto memory 注入 |
| `ENABLE_PROMPT_CACHING_1H` | 可选请求 1 小时 prompt cache TTL |
| `ENABLE_TOOL_SEARCH` | 控制 MCP tool search |
| `CLAUDE_CODE_ENABLE_TELEMETRY` | 启用 telemetry |

长期配置建议写进 `~/.claude/settings.json` 的 `env`,但不要把团队共享项目文件里写入个人 Key。

## 终端快捷键和输入

| 功能 | 默认或建议 |
| --- | --- |
| 换行 | Shift+Enter,不支持时用反斜杠后 Enter |
| Vim mode | 在交互模式中开启 Vim keybindings |
| Option/Alt 快捷键 | macOS 终端可能要单独启用 |
| 终端 bell | 用 Notification hook 播放声音或通知 |
| tmux | 确认 shell integration、copy mode 和颜色 |
| 颜色主题 | 用 `/theme` 或自定义 theme |

如果 Shift+Enter 不工作,运行:

```text
/terminal-setup
```

某些终端或 JetBrains 内置终端不支持这个方案,需要使用替代快捷键。

## Fullscreen rendering

Fullscreen rendering 提供更稳定的全屏渲染、鼠标和 transcript 浏览体验。

| 能力 | 快捷键 |
| --- | --- |
| 进入 transcript mode | `Ctrl+o` |
| 搜索 | `/` |
| 下一个/上一个结果 | `n` / `N` |
| 上下滚动 | `j` / `k` 或方向键 |
| 半页滚动 | `Ctrl+u` / `Ctrl+d` |
| 退出 transcript mode | `Esc` 或 `q` |

如果你依赖原生终端选择文本,可以保留 native selection。tmux 下要同时考虑 tmux 自己的 copy mode。

## Voice dictation

语音输入适合长 prompt、移动场景或不方便打字时使用。

| 命令 | 效果 |
| --- | --- |
| `/voice` | 切换语音输入 |
| `/voice hold` | 按住录音 |
| `/voice tap` | 点击开始,再次点击发送 |
| `/voice off` | 关闭 |

常见问题:

| 问题 | 处理 |
| --- | --- |
| macOS 没有麦克风权限 | 到系统设置允许终端或 IDE |
| 语言识别不准 | 调整 dictation language |
| 快捷键冲突 | 重绑 dictation key |
| SSH/容器中不可用 | 在本机终端侧处理输入 |

## Deep links

Deep links 用 `claude-cli://` 从 runbook、告警、dashboard 或内部平台打开 Claude Code。

| 参数 | 用途 |
| --- | --- |
| `q` | 预填 prompt,需要 URL encode,最多约 5000 字符 |
| `cwd` | 绝对路径作为工作目录 |
| `repo` | GitHub `owner/name`,匹配本地曾见过的 clone |

示例:

```text
claude-cli://open?q=Investigate%20the%205xx%20rate&repo=acme/web-gateway
```

不要在 deep link 里放 secrets。敏感信息由本地工具或安全存储读取。

## PATH 和冲突安装

| 症状 | 处理 |
| --- | --- |
| `command not found: claude` | 检查 PATH,重启 shell |
| PowerShell 找不到 `claude` | 确认安装目录进入 PATH |
| 多个 `claude` | 用 `which -a claude` 或 Windows `where claude` |
| Desktop 覆盖 CLI | 确认期望的 binary 排在 PATH 前面 |
| WSL exec format error | 确认不是 Windows binary 被 WSL 调用 |

## 缓存策略

| 操作 | 5m/1h cache 影响 |
| --- | --- |
| `claude -p` 一次性任务 | 多数是新 session,只复用稳定 system/tools 前缀 |
| `claude -c` | 继续最近历史,更可能读缓存 |
| `claude -r` | 恢复指定 session,取决于历史和 TTL |
| 切换 env/model/provider | 通常改变前缀或缓存命名空间 |
| 启用/禁用 MCP 或插件 | 工具 schema 变化可能导致 miss |
| `/terminal-setup`、theme、voice | 通常不显著影响模型缓存 |

默认不写时走 5 分钟 TTL。如果你在 1 小时内反复进入同一个大项目,可考虑:

```bash
export ENABLE_PROMPT_CACHING_1H=1
```

## 官方参考

- [CLI reference](https://code.claude.com/docs/en/cli-reference.md)
- [Advanced setup](https://code.claude.com/docs/en/setup.md)
- [Environment variables](https://code.claude.com/docs/en/env-vars.md)
- [Terminal config](https://code.claude.com/docs/en/terminal-config.md)
- [Keybindings](https://code.claude.com/docs/en/keybindings.md)
- [Fullscreen](https://code.claude.com/docs/en/fullscreen.md)
- [Voice dictation](https://code.claude.com/docs/en/voice-dictation.md)
- [Deep links](https://code.claude.com/docs/en/deep-links.md)
- [Troubleshoot install](https://code.claude.com/docs/en/troubleshoot-install.md)