> For the complete documentation index, see [llms.txt](https://tinyhumans.gitbook.io/openhuman/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://tinyhumans.gitbook.io/openhuman/zh/kai-fa/claude-code.md).

# Claude Code CLI 提供方

通过 Claude Code CLI 路由聊天工作负载。

OpenHuman 可以通过 Anthropic 的 `claude` CLI 发送任何聊天工作负载，而不是直接调用 Anthropic HTTP API。CLI 负责模型选择、身份验证和提示缓存。OpenHuman 将其作为一个长生命周期的子进程运行，可恢复会话、解析其 stream-json 输出，并为其提供一个 MCP 端点，以便模型可以访问 OpenHuman 状态（内存、线程、代理、搜索）。这是多个可插拔 LLM 后端之一。完整列表见 [引擎](/openhuman/zh/kai-fa/engines.md) 。

`tinyagents-harness` （vendor/tinyagents）拥有该提供者， `ClaudeCodeProvider`。参见 [其 README](https://github.com/tinyhumansai/tinyagents/blob/main/crates/tinyagents-harness/src/providers/claude_code/README.md) 中包含文件映射和实现说明。OpenHuman 仅在 `crates/openhuman-core/src/inference/provider/factory/subprocess_providers.rs`中将其接入，该处提供 MCP 端点（`OpenHumanMcpEndpoint`，见下）并将结果模型字符串读回到其自身的路由中。

## 要求

* Claude Code CLI 2.0.0 或更高版本（`MIN_CLI_VERSION`）。它可以位于 `PATH`中、受支持的已知安装位置，或通过 `OPENHUMAN_CLAUDE_CLI=/abs/path/to/claude`.
* 在 `ANTHROPIC_API_KEY`中的 Anthropic API 密钥，或现有的 `~/.claude/.credentials.json` 来自 `claude login`.
* 该 `http-server` Cargo 功能（默认开启）。OpenHuman 通过回环 HTTP 端点（`crate::mcp::server::ensure_local_http`）将其 MCP 工具暴露给 CLI，而不是把 `openhuman-core mcp` 作为子进程运行。没有该功能时提供者仍会运行，但 CLI 无法获得 OpenHuman 工具。

## 通过 CLI 路由工作负载

使用提供者前缀 `claude-code:<model>[@<temperature>]`。可通过标准推理设置按角色设置：

```bash
# 通过 JSON-RPC 更新端点：
openhuman-core rpc openhuman.inference_update_model_settings \
  --json '{"chat_provider":"claude-code:claude-sonnet-4-5"}'
```

| 角色字符串                | 更新的字段      |
| -------------------- | ---------- |
| `chat_provider`      | 前台聊天回复     |
| `reasoning_provider` | 长上下文推理工作负载 |
| `agentic_provider`   | 多步骤代理循环    |

设置为 `claude-code:<model>` 会为每次轮次启动一个新的 `claude` 子进程。并发数上限为 `MAX_CONCURRENT_TURNS = 4` 每个 `ClaudeCodeProvider` 实例（见 [按轮次行为](#per-turn-behavior)).

## 验证安装

状态 RPC 位于推理命名空间中：

```bash
openhuman-core rpc openhuman.inference_claude_code_status
```

它返回以下之一（`CliStatus` 在 [`tinyagents-harness`的 `claude_code/types.rs`](https://github.com/tinyhumansai/tinyagents/blob/main/crates/tinyagents-harness/src/providers/claude_code/types.rs)):

* `{"status":"ok","version":"2.0.4","path":"/usr/local/bin/claude"}`：已就绪
* `{"status":"not_installed"}`：未找到可用的 `claude` ，通过已配置的覆盖项找到， `PATH`或受支持的回退位置
* `{"status":"outdated","version":"1.9.0","min_required":"2.0.0","path":"..."}`：升级 CLI
* `{"status":"unusable","path":"...","reason":"..."}`：二进制文件存在，但版本探测失败

二进制查找检查 `OPENHUMAN_CLAUDE_CLI` 优先，然后 `PATH`，再然后是有序的回退位置。回退覆盖原生安装程序以及常见的用户本地、Bun、npm 全局和 Homebrew 安装。当通过回退找到 CLI 时，其目录和用户 bin 目录会被预置到子进程 `PATH`中。继承的条目仍然可用。

设置面板通过以下项显示相同状态： `ClaudeCodeStatusCard` ([`app/src/components/settings/panels/ai/ClaudeCodeStatusCard.tsx`](https://github.com/tinyhumansai/openhuman/blob/main/app/src/components/settings/panels/ai/ClaudeCodeStatusCard.tsx)).

## 按轮次行为

`ClaudeCodeProvider::run_chat` 获取 `MAX_CONCURRENT_TURNS` （4）个信号量许可，再加上每线程一个互斥锁，以确保同一会话 UUID 上不会因两个重叠调用而发生竞争。然后每一轮：

1. 从 `<workspace_dir>/claude-code-sessions.json`中解析每线程会话 UUID。新线程会获得一个新的 RFC 4122 v4 UUID，因为 CLI 对 `--resume`.
2. 要求 v4。 `向主机的` McpEndpointProvider`OpenHumanMcpEndpoint`请求一个 MCP 端点。OpenHuman 的实现（`crate::mcp::server::ensure_local_http`，仅限回环）会按核心懒加载启动一个进程内 HTTP MCP 服务器（ `--mcp-config` 在其 `Authorization` 头中携带该令牌。如果端点启动失败，该轮仍会运行，只是没有 OpenHuman 工具。
3. 使用以下方式启动 CLI：
   * `-p --input-format stream-json --output-format stream-json --verbose --include-partial-messages --add-dir <project_dir>`
   * `--mcp-config <scratch>/openhuman-mcp-config.json --strict-mcp-config` 当端点已解析时，因此只有已配置的 MCP 服务器可见
   * `--permission-mode acceptEdits` （默认）或 `bypassPermissions` （完全访问，见下文）
   * 默认情况下， `--disallowedTools Bash,BashOutput,KillShell,WebFetch,WebSearch,Task`，因此 Claude Code 自身的 shell、网络和子代理内置功能保持关闭，而 OpenHuman 工具（`mcp__openhuman__*`）是访问这些能力的唯一方式。启用完全访问时会省略该标志
   * `--session-id <uuid>` 在第一轮时， `--resume <uuid>` 此后
   * `--model <model>` （后缀部分，位于 `claude-code:`)
   * `--append-system-prompt-file <scratch>/append-system-prompt.txt` 如果对话包含系统消息。它是一个文件而不是参数，因此较大的测试提示不会触及 Windows 的参数长度限制
4. 管道传入 stdin。新会话会把完整对话历史折叠进文本前言中。 `--resume` 只会收到待处理的用户轮次，因为 CLI 已经持有较早的上下文。
5. 将 stdout 通过 JSONL 解析器，再经事件映射器，流入 `ProviderDelta`，位于请求的 `stream` sink。

如果 CLI 以非零状态退出，驱动程序会返回其 stderr（上限 16 KiB）作为错误消息。

在 macOS 上，启动默认在 Seatbelt 沙盒（`sandbox-exec`）中运行，当 `/usr/bin/sandbox-exec` 存在时。设置 `OPENHUMAN_CLAUDE_CODE_SANDBOX=0` 可选择退出。该配置文件会阻止在第一个 `.openhuman*`命名祖先下的读取和写入， `workspace_dir`其中保存了该提供者自己的会话存储和设置。它不会限制 CLI 自身的文件工具。Linux 和 Windows 目前还没有 OS 级隔离墙。

### 权限姿态与完全访问

默认的 `acceptEdits`，将 Claude Code 的权限限制为仅可读取和编辑 `project_dir` 下的文件，并禁用 shell、网络和 `Task` 访问，通过 `--disallowedTools`。你可以通过保存在 `<workspace_dir>/claude_code_settings.json`中的设置开关，或通过 `OPENHUMAN_CLAUDE_CODE_PERMISSION_MODE=bypass|bypassPermissions|full`选择完全访问（包括 Bash 在内的全部 Claude Code 工具集）。这是一个显式选择。仅启用该提供者绝不会授予 shell 或网络访问权限。

## 身份验证解析顺序

1. `ANTHROPIC_API_KEY` 环境变量（最高优先级，设置在启动的子进程上）。
2. `~/.claude/.credentials.json`：CLI 自己的登录来自 `claude login` （Pro 或 Max 订阅）。OpenHuman 会让 `ANTHROPIC_API_KEY` 在子进程中保持未设置，因此 CLI 会读取其自己的凭据。在 macOS 上，它们位于 Keychain 中，服务名称为 `Claude Code-credentials` 。
3. 都不是：CLI 会以身份验证错误失败。

该 `openhuman.inference_claude_code_auth_status` RPC 为 Settings > AI 面板报告更丰富的状态。它运行 `claude auth status --json` 并设置 10 秒超时，而不是读取凭据文件，因为 macOS 登录存放在 Keychain 中，而不在磁盘上。

## 暴露给 CLI 的工具面

CLI 将这些工具视为 `mcp__openhuman__<name>`，通过上文所述的回环 HTTP MCP 端点提供。这与位于 [`crates/openhuman-core/src/mcp/server/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/mcp/server/README.md) 中的 stdio MCP 服务器向其他 MCP 客户端暴露的是同一套工具：

* `core.list_tools`, `core.tool_instructions`
* `memory.recall`, `memory.fetch`, `memory.list`, `memory.learn`, `memory.forget`
* `agent.list_subagents`, `agent.run_subagent` （写入，标记为 `destructiveHint` ，如 MCP 规范所要求）
* `searxng_search`

MCP 服务器会强制执行 `SecurityPolicy::ToolOperation` 检查。 `agent.run_subagent`, `memory.learn` 和 `memory.forget` 写入。其余均为只读。CLI 自己的 `tool_use` 块（其内部的 Read、Bash 及类似调用）永远不会作为 harness 工具调用到达 OpenHuman，因为这些调用在流中出现时，CLI 已经执行完了。 `event_mapper.rs` 仅会从可见文本中去除它们的参数 JSON。

## 限制

* 当 Claude Code 提供者可用粘贴图片时，视觉输入会作为原生图像块转发。无法读取的图片会作为一条简短文本通知发送。
* 路由到 `claude-code:` 的每个角色都共享同一个 `MAX_CONCURRENT_TURNS` 信号量；在高负载下，一轮会在队列中等待，而不是快速失败。
* 来自 CLI 的成本统计 `result.total_cost_usd` 会在映射器中被捕获，但尚未接入 OpenHuman 的成本跟踪（[`crates/openhuman-core/src/platform/cost/`](https://github.com/tinyhumansai/openhuman/tree/main/crates/openhuman-core/src/platform/cost/README.md)).
* Linux 和 Windows 上 CLI 以非受限方式运行；Seatbelt 沙盒仅适用于 macOS。