create-project-hapi

name	create-project-hapi
description	为指定项目创建完全隔离的 hapi（Claude Code On the Go）实例，包括独立数据目录、LaunchAgent 持久化、zsh wrapper 和 app.hapi.run 直连 URL。与全局 ~/.hapi 互不干扰。
disable-model-invocation	false
argument-hints	<project-dir> [hub-port=3007]

create-project-hapi

为项目单独开一个 hapi 实例，与全局 ~/.hapi 完全隔离。适合：

• 一台机器上维护多个项目的独立 hapi 配置、token、relay
• 项目级 hapi 随用户登录自动启动，不依赖当前终端
• 团队复用同一套项目级 hapi 配置

前置条件

• macOS
• hapi 已通过 Homebrew 安装：/opt/homebrew/bin/hapi
• 使用 zsh
• 已知目标项目根目录绝对路径

参数

• <project-dir>：项目根目录绝对路径
• [hub-port]：可选，默认 3007，避免与全局 hapi hub 3006 冲突

执行步骤

1. 设置变量

PROJECT_DIR="/path/to/project"   # 替换为实际路径
PROJECT_NAME=$(basename "$PROJECT_DIR")
HAPI_PORT="${2:-3007}"
HAPI_HOME="$PROJECT_DIR/.hapi"
PLIST_DIR="$HOME/Library/LaunchAgents"

2. 创建独立 HAPI_HOME 并生成 token

mkdir -p "$HAPI_HOME"
HAPI_HOME="$HAPI_HOME" HAPI_LISTEN_PORT="$HAPI_PORT" hapi hub --relay

首次启动会生成新的 cliApiToken 并保存到 $HAPI_HOME/settings.json。终端会打印 relay URL，例如：

https://xxxxxx.relay.hapi.run

记下 token 和 relay URL。token 可通过以下命令再次读取：

python3 -c "import json; print(json.load(open('$HAPI_HOME/settings.json'))['cliApiToken'])"

3. 创建 LaunchAgent plist

Hub（带 relay）

文件：$PLIST_DIR/com.hapi.$PROJECT_NAME.hub.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hapi.PROJECT_NAME.hub</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/hapi</string>
        <string>hub</string>
        <string>--relay</string>
    </array>
    <key>WorkingDirectory</key>
    <string>PROJECT_DIR</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>HAPI_HOME</key>
        HAPI_HOME
        HAPI_LISTEN_PORT
        HAPI_PORT
        PATH
        /opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
    
    RunAtLoad
    
    KeepAlive
    
    ThrottleInterval
    10
    StandardOutPath
    HOME/Library/Logs/hapi/PROJECT_NAME-hub.log
    StandardErrorPath
    HOME/Library/Logs/hapi/PROJECT_NAME-hub-error.log

Runner

文件：$PLIST_DIR/com.hapi.$PROJECT_NAME.runner.plist

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hapi.PROJECT_NAME.runner</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/hapi</string>
        <string>runner</string>
        <string>start</string>
    </array>
    <key>WorkingDirectory</key>
    <string>PROJECT_DIR</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>HAPI_HOME</key>
        HAPI_HOME
        HAPI_API_URL
        http://localhost:HAPI_PORT
        
        HAPI_CLAUDE_PATH
        HOME/.hapi/claude-wrappers/hapi-claude
        PATH
        /opt/homebrew/bin:/opt/homebrew/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
    
    RunAtLoad
    
    KeepAlive
    
    ThrottleInterval
    10
    StandardOutPath
    HOME/Library/Logs/hapi/PROJECT_NAME-runner.log
    StandardErrorPath
    HOME/Library/Logs/hapi/PROJECT_NAME-runner-error.log

替换占位符：PROJECT_NAME、PROJECT_DIR、HAPI_HOME、HAPI_PORT、HOME。

4. 加载 LaunchAgent

mkdir -p "$HOME/Library/Logs/hapi"
launchctl load -w "$PLIST_DIR/com.hapi.$PROJECT_NAME.hub.plist"
launchctl load -w "$PLIST_DIR/com.hapi.$PROJECT_NAME.runner.plist"

5. 创建 Claude 模式 wrapper 脚本

hapi 默认调用系统 claude 命令。若希望 hapi 使用 ckh/cg 等自定义 Claude 启动方式（对应 ~/.cp/*.json 的 settings），需要创建一个 wrapper 脚本，并通过 HAPI_CLAUDE_PATH 环境变量让 hapi 使用它。

当 hapi 启动 direct-connect / runner 会话时，会透传一个自己的 --settings（session-hook，用于注入 hapi 的 SessionStart hook）。这个 session-hook 如果直接覆盖 mode settings，会导致 ANTHROPIC_BASE_URL 等 provider env 丢失。因此 wrapper 需要把 mode settings 与 hapi 透传的 session-hook 合并后再传给 Claude。

创建文件：$HOME/.hapi/claude-wrappers/hapi-claude

#!/bin/bash
# hapi-claude wrapper：让 hapi 可以按 cg/ckh/ck 等模式启动 Claude，
# 复现 ~/.zshrc 中对应函数的行为（版本 + settings + headers patch）。
# 当 hapi 透传自己的 --settings（如 session-hook）时，会将其与 mode settings 合并，
# 避免 session-hook 覆盖掉 provider 相关的 env 配置。

set -euo pipefail

mode="${HAPI_CLAUDE_MODE:-}"

# 如果 mode 未设置，尝试从项目 HAPI_HOME 的 claude-mode 文件读取默认模式
if [[ -z "$mode" ]]; then
  if [[ -n "${HAPI_HOME:-}" && -f "$HAPI_HOME/claude-mode" ]]; then
    mode=$(<"$HAPI_HOME/claude-mode")
    mode="${mode//[[:space:]]/}"
  fi
fi

if [[ -z "$mode" ]]; then
  echo "HAPI_CLAUDE_MODE is not set, falling back to system claude" >&2
  exec claude "$@"
fi

case "$mode" in
  cg)   code=700000; binary="$HOME/.cc-expand/bin/claude-70w"; settings="$HOME/.cp/glm.json" ;;
  ck)   code=270000; binary="$HOME/.cc-expand/bin/claude-27w"; settings="$HOME/.cp/kimi.json" ;;
  ckh)  code=270000; binary="$HOME/.cc-expand/bin/claude-27w"; settings= ;;
  ckz)  code=270000; binary=; settings= ;;
  ckzh) code=270000; binary=; settings= ;;
  cks)  code=270000; binary=; settings= ;;
  cksh) code=270000; binary=; settings= ;;
  ckg)  code=270000; binary=; settings= ;;
  ckgh) code=270000; binary=; settings= ;;
  cv)   code=700000; binary=; settings= ;;
  cvg)  code=700000; binary=; settings= ;;
  cds)  code=700000; binary=; settings= ;;
  cdsf) code=700000; binary=; settings= ;;
  cmm)  code=700000; binary=; settings= ;;
  cmmf) code=201000; binary=; settings= ;;
  cog)  code=700000; binary=; settings= ;;
  coq)  code=270000; binary=; settings= ;;
  cods) code=700000; binary=; settings= ;;
  *)
      >&2
     1
    ;;


 [[ ! -x  ]]; 
    >&2
   1


 [[ ! -f  ]]; 
    >&2
   1




hapi_settings=
remaining_args=()
i=0
 [[  -lt  ]]; 
  arg=
   [[  ==  ]]; 
     [[ $((i+)) -lt  ]]; 
      hapi_settings=
      i=$((i+))
      
    
   [[  == --settings=* ]]; 
    hapi_settings=
    i=$((i+))
    
  
  remaining_args+=()
  i=$((i+))



tmpdir=$( -d)
 700 
tmp_settings=

 [[ -n  && -f  ]]; 
  jq --arg v  -s    > 

  jq --arg v    > 

 600 

() {
   -rf 
}
 cleanup EXIT

  --settings  --dangerously-skip-permissions 

然后赋权：

chmod +x "$HOME/.hapi/claude-wrappers/hapi-claude"

6. 设置项目默认 Claude 模式

runner 在后台为远程会话启动 Claude 时，没有 shell wrapper 来传 ckh/cg 等模式。因此需要把项目默认模式写到 $HAPI_HOME/claude-mode，wrapper 在 HAPI_CLAUDE_MODE 为空时会读取它。

# 例如默认使用 ckh
mkdir -p "$HAPI_HOME"
echo "ckh" > "$HAPI_HOME/claude-mode"

之后每次在项目目录内用 hapi ckh ... / hapi cg ... 等启动，zsh wrapper 都会自动更新这个文件，所以远程会话会跟最近一次本地使用的模式保持一致。

7. 配置 zsh wrapper

在 ~/.zshrc 中添加一个函数，使进入该项目目录后运行 hapi 命令自动使用项目级实例，并在 $HAPI_HOME/url.txt 写入 app.hapi.run 直连 URL。同时支持：

• 首参数指定 Claude 启动模式（如 hapi ckh hub --relay）
• 把 Claude 参数写在 hapi 子命令前（如 hapi ckh --continue hub --relay），wrapper 会自动把 Claude 参数挪到子命令后面透传

hapi() {
  local project_dir="PROJECT_DIR"
  local hapi_subcommands=(hub runner auth codex gemini opencode mcp connect notify doctor server)
  local mode=""

  # 1. 解析首参数是否为 Claude 启动模式
  case "${1:-}" in
    cg|ck|ckh|ckz|ckzh|cks|cksh|ckg|ckgh|cv|cvg|cds|cdsf|cmm|cmmf|cog|coq|cods)
      mode="$1"
      shift
      ;;
  esac

  # 2. 拆分 Claude 参数与 hapi 子命令参数
  # hapi CLI 要求子命令在前、Claude 选项在后，所以把 Claude 参数挪到子命令后面透传。
  local claude_args=()
  local hapi_args=()
  local found_subcmd=0
  while [[ $# -gt 0 ]]; do
    local is_subcmd=0
    for sub in "${hapi_subcommands[@]}"; do
      if [[ "$1" == "$sub" ]]; then
        is_subcmd=1
        break
      fi
    done
    if [[ $is_subcmd -eq 1 ]]; then
      found_subcmd=1
    fi
    if [[ $found_subcmd -eq 1 ]]; then
      hapi_args+=("$1")
    else
      claude_args+=()
    
    
  

   all_args=( )
   hapi_home=
   url_file=

  
  
   [[ -n  &&  == * ]]; 
      > 
  

   [[  == * ]]; 
     token=
     [[ -f  ]]; 
      token=$(python3 -c  2>/dev/null)
    
     relay_url=
     hub_log=
     [[ -f  ]]; 
      relay_url=$( grep -oE   |  -1)
    
     [[ -n  && -n  ]]; 
       encoded_hub=$(python3 -c )
        > 
    
     [[ -n  ]]; 
      HAPI_CLAUDE_PATH= \
      HAPI_CLAUDE_MODE= \
      HAPI_HOME= \
      HAPI_LISTEN_PORT= \
      HAPI_API_URL= \
       hapi 
    
      HAPI_HOME= \
      HAPI_LISTEN_PORT= \
      HAPI_API_URL= \
       hapi 
    
  
     [[ -n  ]]; 
      HAPI_CLAUDE_PATH= \
      HAPI_CLAUDE_MODE= \
       hapi 
    
       hapi 
    
  
}

替换占位符：PROJECT_DIR、PROJECT_NAME、HAPI_PORT。

注意：这里使用 command grep 绕过可能存在的 grep → rg shadow，避免正则解析错误。

注意：hapi CLI 要求 Claude 参数出现在子命令之后，wrapper 会自动重排，因此 hapi ckh --continue hub --relay 等价于 hapi ckh hub --relay --continue。

7. 忽略 .hapi 目录

在项目 .gitignore 中加入：

# hapi local instance data (tokens, logs, runtime)
.hapi/

8. 验证

cd "$PROJECT_DIR"
hapi runner status        # 应显示 Runner is running
cat .hapi/url.txt         # 应输出 app.hapi.run 直连 URL
hapi ckh hub --relay      # 用 ckh 模式启动项目级 hapi hub（带 relay）

连接 app.hapi.run

打开 .hapi/url.txt 中的 URL，或在浏览器中手动操作：

1. 打开 https://app.hapi.run
2. 点右上角 Hub (自定义)
3. 服务器地址填入 relay URL（如 https://xxxxxx.relay.hapi.run）
4. 保存
5. 访问令牌填入 cliApiToken
6. 登录

如果提示 Invalid access token，检查浏览器 localStorage 中的 hapi_hub_url 是否与当前项目的 relay URL 一致，不一致则清除 localStorage 或手动切换 Hub。

Claude 启动模式

zsh wrapper 支持把 cg/ckh/ck 等作为 hapi 的首参数，hapi 会通过 $HOME/.hapi/claude-wrappers/hapi-claude 启动对应 settings 的 Claude：

hapi ckh                 # 用 kimi-highspeed settings 启动 hapi direct-connect
hapi ckh hub --relay     # 用 ckh 模式启动项目级 hapi hub
hapi ckh --continue hub --relay   # 同上，但把 --continue 透传给 Claude
hapi cg runner status    # 用 glm settings 查看 runner 状态

由于 hapi CLI 要求 Claude 参数出现在子命令之后，wrapper 会自动把 --continue 这类 Claude 参数挪到子命令后面（例如 hapi ckh --continue hub --relay 实际调用 hapi hub --relay --continue）。

远程会话的模式

runner 在后台为远程（app.hapi.run）会话启动 Claude 时，没有 shell 可以传 ckh/cg 参数，因此它会读取 $HAPI_HOME/claude-mode 文件作为默认模式。zsh wrapper 每次在项目目录内使用带 mode 的命令时，都会自动更新这个文件，保证远程会话与最近一次本地使用的模式一致。

如果想手动切换远程默认模式：

echo "cg" > /path/to/project/.hapi/claude-mode

不带模式参数时，hapi 保持默认行为（调用系统 claude）。

支持的 mode 与 ~/.zshrc 中的 Claude 启动函数一一对应：

mode	code	settings 文件
cg	700000	~/.cp/glm.json
ck	270000	~/.cp/kimi.json
ckh	270000	~/.cp/kimi-highspeed.json
ckz	270000	~/.cp/kimi-zhongge.json
ckzh	270000	~/.cp/kimi-zhongge-highspeed.json
cks	270000	~/.cp/kimi-shipeng.json
cksh	270000	~/.cp/kimi-shipeng-highspeed.json
ckg	270000	~/.cp/kimi-gaohui.json
ckgh	270000	~/.cp/kimi-gaohui-highspeed.json
cv	700000	~/.cp/volc.json
cvg	700000	~/.cp/volc-glm.json
cds	700000	~/.cp/ds.json
cdsf	700000	~/.cp/ds-flash.json
cmm	700000	~/.cp/minimax.json
cmmf	201000	~/.cp/minimax-flash.json
cog	700000	~/.cp/opencode-glm.json
coq	270000	~/.cp/opencode-qwen.json
cods	700000	~/.cp/opencode-ds.json

卸载

PROJECT_DIR="/path/to/project"
PROJECT_NAME=$(basename "$PROJECT_DIR")
launchctl unload -w "$HOME/Library/LaunchAgents/com.hapi.$PROJECT_NAME.hub.plist"
launchctl unload -w "$HOME/Library/LaunchAgents/com.hapi.$PROJECT_NAME.runner.plist"
rm -f "$HOME/Library/LaunchAgents/com.hapi.$PROJECT_NAME."*.plist
rm -rf "$PROJECT_DIR/.hapi"
# 同时删除 ~/.zshrc 中对应的 hapi() wrapper 段落

注意事项

• 多个 hapi relay 实例可以共存，tunwg 会自动分配不同子域名。
• token 保存在 $HAPI_HOME/settings.json 中，不要提交到 git。
• .hapi/ 必须加入 .gitignore。
• 每个项目实例使用独立端口，避免与全局 hub 3006 冲突。