Claude

在 Kaiwu（远程模式）中配置 Claude，包括 Agent SDK、部分流式传输和 /rewind。

本文介绍 Kaiwu 与 Claude Code 的集成方式，以及各项 Claude 专有设置的具体作用。

运行模式：本地模式与远程模式

Kaiwu 支持两种 Claude 运行方式：

本地模式：直接在终端中运行 Claude Code 自带的 TUI。
远程模式：通过 Kaiwu 界面操控 Claude，但 Claude 依然在本地设备上运行（由 Kaiwu 在后台拉起 claude 进程）。

远程模式提供三种实现方案，并按以下优先级依次选用：若启用了统一终端则优先使用；未启用则使用 Agent SDK；最后回退至旧版实现。

运行时	Kaiwu 驱动 Claude 的方式	是否需要接入终端？
统一终端（需手动开启）	Kaiwu 在终端会话中托管 Claude Code 自带的 TUI，并自动向其输入框中键入提示词，使客户端与终端共享同一个 Claude Code 运行实例。	是
Agent SDK（默认）	在后台进程中通过官方 `@anthropic-ai/claude-agent-sdk` 运行 Claude，对外发布功能能力，并可选支持文件检查点。	否
旧版远程模式（回退方案）	较早的类 SDK 垫片方案，通过流式输出格式拉起 `claude`，并转发会话信息的钩子。	否

统一终端默认处于关闭状态。由于它会显著改变会话的运行机制（如交互引导、排队输入、各项运行时控制的实时生效方式等），建议先查阅：Claude 统一终端。

从 Kaiwu 启动，在终端中继续

对于在客户端中启动的会话，Claude 支持 Kaiwu 的接入流程：

在 Kaiwu 客户端中启动 Claude 会话，
由 Kaiwu 在本地设备上以远程模式运行该会话，
随后可使用 Kaiwu attach ⟦K3⟧ 重新接入，
如需直接使用 Claude Code 的原生终端 TUI，可切换至本地模式。

之后你还可以切回远程模式，在 Kaiwu 客户端中继续操作，无需新建会话。

本地控制需从终端发起。请在承载该会话的设备上运行 Kaiwu attach ⟦K4⟧。

若在 Claude 处于本地控制期间从客户端发送消息，Kaiwu 会先将其存入待处理队列。当 Claude 处于空闲状态时，Kaiwu 可切回远程控制并处理队列中的消息。如果 Claude 仍在终端中执行任务，Kaiwu 会等待当前本地轮次执行完毕或中止后再切换，确保客户端消息不会打断 Claude 当前的执行轮次。

在装有 tmux 的设备上，该流程通常基于 tmux 实现接入。在 Windows 上，请使用 Kaiwu 的 Windows 远程会话模式（Windows Terminal、Console 或 Hidden），无需依赖 tmux。

完整工作流程请参见功能特性 → 接入正在运行的会话。

权限与模式

Kaiwu 包含以下两套机制：

与提供商无关的通用权限模式（default、read-only、safe-yolo、yolo）
独立的 Claude 会话模式控制项（包含 Plan）

完整的用户指南（包括 CLI 参数、界面选择器、默认值和生效时机）请参见：

Claude 计划模式

在当前的 Kaiwu 版本中，Plan 位于**模式（Mode）**菜单下，而非普通的权限选择器中。

这一区分非常关键：

Mode = Plan 会改变 Claude 在当前会话中的行为方式
权限模式则依然负责控制审批流程

计划模式本身不会绕过审批。会话处于计划模式时，Claude 依然可以请求权限。

退出计划模式

当 Claude 完成规划后，Kaiwu 会以用户操作请求的形式呈现退出计划模式（Exit Plan Mode）。

常见选项包括：

Approve Plan
Request changes
Approve Plan (Accept Edits)
Approve Plan (Bypass All Permissions)

这些选项决定了 Claude 退出计划模式之后的行为：

Approve Plan：返回常规构建模式
Accept Edits：返回构建模式，并采用放宽编辑限制的权限策略
Bypass All Permissions：返回构建模式，并采用完全放行的 YOLO 权限策略

如果选择请求修改，Claude 将保留在计划模式中继续修改方案，而不会开始执行。

本地与远程模式切换

权限模式以标准方式保存在会话元数据中。因此，在以下场景中权限模式都会跟随会话保持同步：

在另一台设备上打开同一个会话，或
在本地与远程模式之间切换。

部分权限行为由 Kaiwu 自身实现（如工具调用的审批拦截），此类行为可即时更新；另一些行为则依赖 Claude 自身的会话标志位，可能仅在 Claude 启动或恢复时生效。会话内选择器中的“生效策略”（Effective policy）一行，即为当前实际生效规则的权威参考。

启用本地权限桥接后，即使终端持有会话控制权，Claude 的权限提示仍可转发至 Kaiwu。消息发送与权限审批彼此独立：在本地独占控制期间从客户端发送的消息仍会进入待处理队列，直到 Kaiwu 能安全恢复远程处理时才会投递。

安装 Claude Code

请先在设备上安装并认证 Claude Code，然后重启 Kaiwu。

请参考 Anthropic 官方安装指南：

Anthropic 目前支持两种安装方式。建议优先使用其文档中推荐的原生安装程序；若 npm（npm install -g @anthropic-ai/claude-code）更契合你的环境，也可采用。

由 Kaiwu 自动安装

Kaiwu 可代你运行安装程序，该方式会使用 Anthropic 的原生安装程序而非 npm：

kaiwu install provider claude
claude --version

在 Kaiwu 中进行本地认证

Claude 还支持直接在提供商设置中完成设备本地提供商认证。

打开路径：

设置 → AI & Agents → AI 后端 → Claude

在此界面中，你可以：

检查所选设备上 Claude 的登录状态
查看 Kaiwu 是否检测到 CLI 登录、ANTHROPIC_API_KEY 或 ANTHROPIC_AUTH_TOKEN
在 Kaiwu 内调出 Claude 的原生登录流程
点击 Check now 刷新认证状态

点击 Log in 时，Kaiwu 会启动 Claude 并自动发送 /login。

通用用户指南请参见提供商认证。

认证（关联服务）

Claude 可通过 Kaiwu 的关联服务进行认证：

claude-subscription：Claude 订阅凭据
- Setup-token（推荐默认方案）：在任何安装了 Claude Code 的设备上通过 claude setup-token 生成，然后粘贴到 Kaiwu 中
- OAuth：支持各平台的粘贴重定向流程，并在原生端提供应用内浏览器登录
anthropic：Anthropic API 密钥（Anthropic Console）

在客户端中：

设置 → 关联服务 → Claude

在 CLI 中：

# Claude subscription (recommended default)
kaiwu connect claude --setup-token

# Anthropic API key (not subscription)
kaiwu connect claude --api-key

# Subscription OAuth (advanced)
kaiwu connect claude --oauth

更多详细信息（服务 ID、安全模型及环境变量替代机制）请参见：

关联服务

实践建议：

若追求在不同设备间最稳定的 Claude 订阅凭据体验，建议优先选择 setup-token。
若尚未安装或登录 Claude Code，可使用 OAuth。
在新建会话的认证选择器中，兼容 Claude 的后端仅会展示其切实支持的 Claude 相关关联服务选项。

会话交接

Claude 支持在不同设备之间进行 Kaiwu 会话交接。

这意味着你可以：

在一台设备上启动 Claude 会话
将同一个 Kaiwu 会话 ID 交接至另一台设备
在目标设备上继续该会话
必要时还可交接回原设备

重要提示：

设备本地的 Claude 登录状态对于原生 Claude CLI 工作流依然必要
关联服务可以让跨设备连续体验更加顺畅，因为凭据是由账号统一管理，而非仅保存在本地设备
跨设备直接交接会话的能力取决于提供商，Claude 属于支持该特性的提供商之一

参见：

在 Kaiwu 中配置 Claude 的入口

在客户端中：

设置
AI & Agents → AI 后端
Claude (remote)

下方列出的大多数设置项仅对 Claude 远程模式生效。
唯一的例外是实验性：本地权限桥接，该选项对本地模式生效。

设置参考（Claude 远程模式）

设置项	默认值	说明
Use Agent SDK (remote)	开启	启用官方 Agent SDK 远程运行器（`@anthropic-ai/claude-agent-sdk`）。关闭时，Kaiwu 将使用旧版远程运行器。
Setting sources	User + Project	控制加载哪些 Claude 设置项：Project only 仅加载代码仓配置（例如 `CLAUDE.md`）；User + Project 会一并加载用户全局配置（包括用户自定义的 MCP 服务器）；None 忽略两者以获得最高的确定性。
Force-enable Agent Teams (experimental)	关闭	开启后，Kaiwu 会对所有 Claude 启动实例（本地与远程）强制启用 Claude Code 实验性 Agent Teams 特性。关闭时，Kaiwu 不会强制禁用，Claude 将遵循其默认行为。
Experimental: local permission bridge	开启	在本地模式下，将 Claude 权限提示转发到 Kaiwu 中，从而可以在客户端界面中进行批准或拒绝，而无需局限在终端内。
File checkpointing + /rewind	关闭	启用文件检查点捕获以及 `/rewind` 命令（仅限远程 Agent SDK 模式）。此功能会带来额外开销。
Max thinking tokens	Default	设置 Claude 内部思考预算的上限（仅限远程 Agent SDK 模式）。
Disable TODOs	关闭	添加一条远程模式系统指令，要求 Claude 不要在输出中创建 TODO 条目或列表。
Strict MCP server config	关闭	只要有任何 MCP 服务器配置无效即中止远程启动（而非尝试忽略并继续）。
Advanced options (JSON)	空	面向高级用户，用于覆盖 Agent SDK 查询选项的受限白名单（仅限远程 Agent SDK 模式）。无效的 JSON 会被忽略，并向用户弹出警告提示。

Kaiwu 中完整的 MCP 用户指南请参见：

MCP 服务器

环境变量

Kaiwu 没有专门针对 Claude 的“环境变量”CLI 参数。如需为 Claude 设置环境变量：

本地模式：在运行 Kaiwu 之前于 Shell 中导出环境变量（Claude 会自动继承）。
远程模式（通过客户端界面）：在界面的配置文件或会话中设置环境变量（Kaiwu 会将其转发给拉起的 Claude 进程）。

远程 Agent SDK 模式默认使用经过过滤的环境变量，但界面或配置文件中明确指定的环境变量（以及关联服务的认证环境变量）会转发给 Claude 子进程，从而在保证 GitHub 集成等工作流正常运行的同时，避免泄露父进程完整的 process.env。

Kaiwu 中的 Agent Teams（Claude 群体智能）

在 Claude 中启用 Agent Teams 后，Kaiwu 可以支持：

通过 Force-enable Agent Teams (experimental) 设置项，为所有 Claude 启动实例（本地与远程）强制启用 Agent Teams。
将主会话输入框中的用户消息路由至：
- 具体的团队成员（1:1），或
- 团队广播（全员）。
在会话的 Agents 标签页中将 Claude 队员作为一级条目展示，支持重新打开其会话记录、向现有团队中增派队员，以及在必要时将其终止。
既可以从 Agents 侧边栏重新打开队员的工作上下文，也可以从原始的会话记录/工具调用条目中打开。

有关 Agents 侧边栏、子智能体、详情面板行为及 Claude 团队工作流的完整指南，请参见：

路由界面（接收者标签）

当 Claude 会话中存在活跃团队时，会话输入框会显示一个 “To:” 接收者标签。你可以用它来：

发送给 Lead（默认），
选择具体的队员，或
选择 Broadcast。

路由消息以与提供商无关的结构化消息类型（participant_message.v1）存储，因此 Kaiwu 可以将其在会话记录中渲染为独立的卡片样式（而非普通气泡）。

呈现在用户界面的关键规则如下：

Kaiwu 会如实展示你输入的原始内容，
Kaiwu 不会展示 Claude 为执行路由步骤而在内部重写的提示词。

视口感知的默认接收者

当你打开聚焦的工具会话记录视图时：

包含队员派生事件的 Task 会话记录可自动将该队员选为接收者（前提是你未手动选择其他接收者）。
SubAgentRun 会话记录会在任务运行期间自动将正在运行的执行实例选为接收者。

若在该界面上手动选择了其他接收者，则在离开或重新打开该界面前，均以手动选择为准。

接收者选择器中的队员生命周期

接收者选择器与 Claude 团队的当前活跃名单保持同步。

这意味着：

活跃队员始终可作为接收者选用，
只要团队存在，Broadcast 就始终可用，
已终止的队员会从活跃接收者列表中移除。

当前限制：附件与审查评论

路由消息目前不支持：

附件，或
审查评论草稿。

如有此类需求，请作为常规消息发送给 Lead。

常规的非路由会话消息均支持 Kaiwu 附件。

参见：附件与图片预览

本地权限桥接（实验性）

启用实验性：本地权限桥接后：

你可以继续在终端中使用 Claude 的本地 TUI。
权限提示也会同步显示在 Kaiwu 界面中，支持直接在客户端内完成审批。
若桥接不可用，Claude 会回退至终端内的常规权限提示行为。

该特性旨在改善本地模式的易用性：当你想继续使用 Claude 本地运行时，又希望在客户端中保留会话控制权，即可使用此功能。

生效时机：此项为用户级设置，会与你的账号设置同步，并在本地 Claude 会话启动时读取。若在本地会话运行期间更改了此设置，需重启该会话（或从客户端发送任意消息）方可生效。

高级选项（JSON）：白名单

高级 JSON 字段经过了专门的限制，避免破坏 Kaiwu 的控制平面（如钩子、权限、会话处理等核心逻辑）。

当前白名单中允许的键如下：

plugins
betas
maxBudgetUsd
sandbox
additionalDirectories
permissionPromptToolName
tools
systemPrompt
debug
debugFile
stderr

其余所有键均会被忽略。## 文件检查点与 /rewind

启用 File checkpointing + /rewind 后，Kaiwu 会捕获检查点 ID 并提供回滚命令：

/checkpoints 显示已捕获的检查点 ID（按时间倒序排列）。
/rewind ⟦K5⟧ --confirm 将文件回滚至指定检查点。
/rewind --confirm 将文件回滚至最近一次捕获的检查点。

注意事项：

Agent SDK 的回滚仅作用于文件系统，不会删除或重写对话内容。
这与 Claude Code 在 TUI 中的交互式 /rewind 命令不同，后者可以回滚对话上下文和/或文件。Kaiwu 远程环境采用的是 Agent SDK 的回滚行为。
/rewind 需要二次确认，因为该操作会放弃本地的文件修改。
检查点功能仅适用于远程 Agent SDK；由于需要捕获并流式传输检查点信息，速度可能会稍慢。
如果在未启用检查点（或尚未捕获任何检查点）的情况下尝试 /rewind，Kaiwu 会提示当前无可用检查点。