Ctrlk
X/TwitterGithubWebsiteDiscord
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Claude Code CLI 提供方

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

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

tinyagents-harness （vendor/tinyagents）拥有该提供者， ClaudeCodeProvider。参见 其 README 中包含文件映射和实现说明。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>]。可通过标准推理设置按角色设置：

# 通过 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 实例（见 按轮次行为).

验证安装

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

它返回以下之一（CliStatus 在 tinyagents-harness的 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).

按轮次行为

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

  1. 从 <workspace_dir>/claude-code-sessions.json中解析每线程会话 UUID。新线程会获得一个新的 RFC 4122 v4 UUID，因为 CLI 对 --resume.

  2. 要求 v4。 向主机的 McpEndpointProviderOpenHumanMcpEndpoint请求一个 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/ 中的 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/).

  • Linux 和 Windows 上 CLI 以非受限方式运行；Seatbelt 沙盒仅适用于 macOS。

上一页MCP 服务器
下一页Linux 和 Docker 上的 TinyComputer 浏览器

最后更新于